I begun learning Symfony2 one of the things that struck me are the numerous comments above variables and functions like so:
variables example:
/**
* #var string
*/
private $baseUrl = 'news/';
OR:
/**
* #var FeedRepository
*/
private $feedRepo;
Functions:
/**
* #param ArticleQuery $query
* #return QueryBuilder
*/
public function test(){
}
Could someone explain to me why use these and why do the do ..?
PHPDoc is an adaptation of Javadoc for the PHP programming language. It is still an informal standard for commenting PHP code, but it is in the progress of being formalized. It allows external document generators like phpDocumentor to generate documentation of APIs and helps some IDEs such as Zend Studio, NetBeans, JetBrains PhpStorm, ActiveState Komodo Edit and IDE, PHPEdit and Aptana Studio to interpret variable types and other ambiguities in the loosely typed language and to provide improved code completion, type hinting and debugging.
Try for example to use an IDE like PHPStorm and write the following PHP code:
/**
* #param array $test
*/
function mytest($test) {
// ... nothing here
}
Now when you start typing myte you get the autocompletion to suggest mytest(test : array).
As you can see now PHPStorm knows the type of the $test variable thanks to the PHPDoc above.
Related
Is it possible to link to another method/class/property/etc of my project, inline inside the #param tag?
Like this:
/**
* My method's description.
*
* #param string $myArg Pass here result of {#link myOtherMethod()}.
*
* #return bool
*/
public function myMethod($myArg) {
// TODO: code here.
}
...
Both PhpDoc (phpDocumentor) and doxygen support inline-link to other method.
For phpDocumentor
Use:
{#link myOtherMethod()}
Or:
{#link MyClass::myOtherMethod()}
But unlike doxygen, seems inline-link is not everywhere supported,
see PhpDocs: Link to another method in "#deprecated" tag's description?
For doxygen:
{#link #myOtherMethod}
Or:
{#link MyClass#myOtherMethod}
Or even just:
myOtherMethod()
Note that human-readability of un-compiled docs matters,
hence phpDocumentor syntax should be used, because it's more known (by PHP developers at least).
But once doxygen supports that same PhpDoc syntax, it's no issue to generate docs with doxygen, because once docs are compiled, it does not matter with what tool they were compiled, they are readable either way.
I'm using eclipse to build my php applications and the Source > Generate Element Comment function for automatically creating doc blocks.
I'm wondering a bit about the format because the return type is set as full-qualified class name but the parameters not.
Is this a bug of the IDE or is it the common convention?
Here's an example:
/**
* Executes the given service.
*
* #param string $serviceClass
* #param ParametersInterface $inputParams
*
* #return \ZF\Hal\Entity
*/
And I have the following uses:
namespace MyApp;
use ZF\Hal\Entity;
use Zend\Stdlib\ParametersInterface;
It's most likely just a behavior oddity in Eclipse, where the auto-recognition code for parameters is possibly not the same code that auto-recognizes returns. I would bet the parameter recognition is more naive, in that it probably keys specifically off your method signature. So, if your method signature is
public function executeService(string $serviceClass, ParametersInterface $inputParams)
then the auto-doc probably gets exactly just the ParametersInterface you have in the code.
However, if you wrote the code this way
public function executeService(string $serviceClass, Zend\Stdlib\ParametersInterface $inputParams)
then I'd bet the auto-doc would show the fully namespaced name.
It wouldn't hurt to report it to Eclipse (if it's not already been reported).
This may happen if you have use ParametersInterface; with it's path on top of file, so PHP doc takes it into account, but you don't have use ZF\Hal\Entity, so it's inserted in #return with full path.
In PHPStorm it works like this, so probably in Eclipse it works the same
in a Yii Application in PHPStorm i have the following Code:
$datasource = Yii::app()->someComponent;
PHPStorm is now not able to find the definition of method parameters in autocomplete, if i write
$datasource->aMethod(
Is there a way to tell phpstorm the source in order to have a working autocomplete?, e.g.
// #definition components/SomeComponent.php
$datasource = Yii::app()->someComponent;
Thanks,
markus
You could use a PHP Doc comment to tell PHPStorm which type the var has.
/** #var SomeClassName $datasource */
$datasource = Yii::app()->someComponent;
There's better solution. One which makes PhpStorm able to assign Yii::app()->someComponent to class for entire project.
Put in CAplication's php doc (above class):
/**
* #property Someclass $someComponent.
*/
Solved with one line of code. It works with PhpStorm 9.0, haven't tested earlier versions.
I have created a standard Registry class. The registry can then return a new or already created instance of a class by using:
$classObject = $registry->getInstance(Namespace\subdirectories\ClassName);
My project is set up with namespaces, so that is the typical syntax.
All works well, except IDEs like Eclipse luna will no longer have Content Assist, meaning pressing ctrl+space will no longer pop up a screen with the classes public methods.
Has anyone run into this situation before? How did you restore content assist functionality as best as you could? Alternatively, if you could not restore the functionality, what did you do so programming remained somewhat still practical within the project?
I have fixed this issue by using PHPDoc type hinting for my IDE
Example
/**
/* #var \FullClassNamespace\
*/
$private $someVar;
public function __construct() {
$this->someVar = registry->getClassinstance(fullnamespace);
$someVar-> (autocomplete works)
}
It is worth noticing that in some IDEs doing an inline type hinting won't work, as in /** #var namespace */. The initial /** and ending */ must be in separated lines
I think my eclipse's ctrl+clicking links might benefit greatly...
Edit: I'm using eclipse PDT.
Edit 2: I'm very happy with the solution of putting docblocks before functions (and variables) with an #return or #var statement, I've just updated the documentation of my app and now eclipse is showing me what functions are available to what objects!
Awesome.
// [...]
/**
* Return the Request object
*
* #return Zend_Controller_Request_Abstract
*/
public function getRequest()
{
return $this->_request;
}
// [...]
works perfectly with Eclipse PDT. Which plugin do you use?
Short answer: no.
Long answer: consider adding docblocks with #return declarations.
The only way to hint return type in PHP is to use a good IDE like Eclispe PDT or Zend Studio with standard comment block. PHP simply can n not predict return type because it is dynamically typed language so type checking is done in the run time unlike for the statically typed languages like C#, JAVA and C++.