Proper Way to Document Class in Netbeans PHP

Question

For reasons of ease of maintenance AND IDE class auto-completion and member hinting, I\'ve used PHPDoc in my project. Given this example class:

class my_clas         


        

Answer 1

I am not sure about the exact syntax but I am sure that netbeans will adhere to the standard php documentation.

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html http://www.phpdoc.org/

Answer 2

I prefer to use @var above each property and no @property at all. I feel that this allows you to more closely associate the comments with the thing that is being commented on. I.e., the comments for a property are always right next to the property. If you're using the @property style and you've got a big class with a ton of properties, it's entirely possible that the comment which describes a property is pages away from it.

Answer 3

The "property" tag is specifically and explicitly for "magic" properties, meaning any that don't actually appear in the code itself. That's the key reason why the tag occurs only in the class docblock. As such, I'm guessing IDEs that recognize the "property" tag do so from that "it's NOT seen in the code" perspective. Granted, I could understand an expectation that autocomplete should recognize the existence of such a property, and therefore make it available for you. However, my bet is that the IDEs will stick with using only the code itself to build a model, and only use docblock info to supplement the elements that it already sees in the code.

Using the "var" tag is the one proper way to document your "coded" properties. If you want to minimize the lines required in order to use that tag on all the properties, use a one-line docblock:

/** @var int */
public $id;

Also, you could use the docblock template to cut down on docblocks, where tag similarity fits your code:

/** @var string */
public $name;

/**#@+ @var int */
public $id;
public $number;
/**#@-*/

That doesn't seem like much savings in this short list, but it does help when there are lots of properties. Also, it works fine around methods.