I did read a lot about PHP documentation and how to do the comments inside the classes, but I do not know yet if have any pattern to identify the size of a variable. I didn't saw any convention that talk about this kind of information. What I'm doing a Web Service and some parameters has a required size. Example:
What I got:
/**
*
* #access private
* #var string
*/
private $password;
What I want:
/**
*
* #access private
* #var string 10 (<-- size)
*/
private $password;
What I want to know if I write the size after identifying the type is correct. Or if have any way to do that or if I don't have to do.
Theres no need to had the size, actually there's nothing regarding the size in phpdoc
it should be only
/**
* #var <type> [$<var name>]
*/
I hope this helps :)
Related
Can anyone advise where in the PSR standards docs it documents that there should be nothing after the variable type in class member variables?
I used PHP CodeStyle Fixer by doing the following: php-cs-fixer fix MyConsoleCommand.php
...and it removed the variable from the docblock. I have been doing this for some time now and I believed this was correct and standards-compliant.
Can anyone confirm?
/**
- * #var SiteManager $siteManager
+ * #var SiteManager
*/
private $siteManager;
/**
- * #var Registry $doctrine
+ * #var Registry
*/
private $doctrine;
By default all the levels are on and this particulair behaviour comes from the sympfony standard
phpdoc_var_without_name [symfony]
#var and #type annotations should not contain the variable name.
see https://github.com/FriendsOfPHP/PHP-CS-Fixer and search for "phpdoc_var_without_name"
if you don't want to use the Symfony standard do
php php-cs-fixer.phar fix MyConsoleCommand.php --level=psr2
hope it helps
I use docblocks to typehint class properties, and only recently realised that class properties may be grouped as such:
/**
* #var string
*/
private $firstname, $surname, $location;
Which is way easier to read, and shorter, than this:
/**
* #var string
*/
private $firstname;
/**
* #var string
*/
private $surname;
/**
* #var string
*/
private $location;
Would there be any reason not to do this?
I prefer 1st approach, because PSR-2 says "There MUST NOT be more than one property declared per statement.". There are good reasons for that, and here are some of my thoughts I guess authors of PSR-2 had too:
people don't expect to see more than one declaration per line (at least me and my collegues);
it's more difficult to change type of a variable, e.g. of $location from string to a Location class.
it's more difficult to read diffs: the line will be marked as changed by VCS if name of any variable changes, and reviewer will have to read the whole line. Such line has higher probability of changing;
it's not easy to comment a single variable from a group.
I'm trying to document PHP class members with Doxygen (I'm not using PHPDocs because the project involves COCOA programming, so I can use the same tool for both parts).
/**
* This is brief description.
*
* This is detailed description.
*/
private $foo;
This code gets the documentation done right, but I would like to include in the docs the type the var should handle.
I tried to use \var and \property, but then Doxigen does not generate the doc for the var.
//THIS IS NOT WORKING!
/**
* This is brief description.
*
* This is detailed description.
* \var int
*/
private $foo;
I have seen this post:
Doxygen: how to describe class member variables in php?
Seems that \var is not working in Doxyegn, but the post is a bit old and maybe there is something I can do now.
I have follow the bug comments of this feature:
https://bugzilla.gnome.org/show_bug.cgi?id=626105.
In comment number 6 a solution is proposed, adding the var name after the type.
class Mine {
/**
* Definition of variable
* #var string $var
*/
private $var = array();
}
This is working for me.
Simple workaround which generates acceptable results is to add this input filter:
INPUT_FILTER = "sed -e 's/#var\s/#see /'"
Or even better to define an alias:
ALIASES += "var=#see"
It simply replaces #var command with #see command. It is not perfect, but it is very simple and relatively bulletproof.
Small disadvantage is that the type is somewhere in the description instead of the heading. On the other side, if only few properties has type defined, it makes documentation more consistent (headings look the same).
#type works for me:
/** #type string[] */
private $csvData;
/**
* command line parameters
* #type string[]
*/
private $parameters;
Could someone tell me whats the meaning of "#var" in annotations configuration?
For example:
/**
* #Column(type="string", length=20, unique=TRUE)
* #var string
*/
protected $login;
It tells you what type of variable is it. Whether it's integer, string or an object, for example. It's used for auto-documentating processes
This is an annotation used for automatic documentation generation with phpDocumentor. For #var see their documentation.
I recently started to add comments on properties declaration on my php classes. The main reason is that without thoses comments, NetBeans don't understand what to do with the properties and so i get no autocompletion. Here what it looks like :
/**
* #var MyClass what blabla about the instance.
*/
public $myClassInstance;
The question is : when I have more then 1 instance of the same class instanciated on properties, is there a way to "multi-comment" ? using only once #var for every property under it ? (as follow)
/**
* #var MyClass what blabla about the instance.
*/
public $myClassInstance;
public $myClassInstance2;
Ok, it seems stupid to do that at once, but it comes handy when declaring primary types for exemple, so it'll looks better and have less "trash" :
/**
* #var Integer blabla
*/
public $index;
public $start;
public $end;
I assume netbeans uses the phpDocumentor. From the docs it doesn't result that such a thing is possible.
There's no official standard for phpdoc comments, and especially their interpretation by IDEs. Probably your best bet in this case would be to have #var phpdoc for each variable separately.
Ok, thanks for your answers :) finally I ended up doing one line comments using Phpdoc structure like that :
/** #var Professionnel */
protected $auteur;
/** #var Categorie */
protected $categ;
So I have both things I looked for : less comments and autocomplete :)