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_class {
    public $id;
    public $name;
    public $number;

    public function __construct() {
        //Do something
    }

    public function Rename($name) {
        $this->name = $name;
    }
}

I would prefer to document all properties ($id, $name and $number) with the class documentation itself, which is above the class declaration, and then place documentation for methods (if necessary) above each method. Here is what I ultimately want my class to look like:

/**
 * Represents an example class for Stackoverflow
 * 
 * @property int $id The id of the object
 * @property string $name The name of the object 
 * @property int $number The number of the object
 */
class my_class {
    public $id;
    public $name;
    public $number;

    public function __construct() {
        //Do something
    }

    /**
     * Renames the object
     * @param string $name Name to rename object
     */
    public function Rename($name) {
        $this->name = $name;
    }
}

This is precisely what I prefer to have as documentation, however Netbeans' autocomplete fails to operate correctly, as it lists each property twice. For example, if I start typing $my_class_object->i the auto-complete will list two $id properties: one as described in my PHPDoc, and another is described as an unknown variable with "PHPDoc Not Found".

There is a solution that works to solve the Netbeans issue - add a @var PHPDoc block above each property, however I think it unnecessarily clutters up my class, especially some of my classes that have 10+ properties.

Is there a [good] solution to both of my issues (clean doc, proper Netbeans hinting), or am I going about this incorrectly?

Calandra

Answer 1

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.

Filomenafiloplume

Was unaware of the docblock template - though I occasionally need to provide additional comment on the use of variables, this should help me meet middle ground in keeping the code well documented while also keeping the auto-complete up-to-snuff. Thanks! – Calandra

You can combine docblock templates with actual docblocks, resulting in the template's info being "appended" to the individual docblocks. In the example above, you could still put a specific docblock on $id and another on $number, with other info rather than the shared var tag. In the resulting docs, both variables would pick up the int datatype. – Filomenafiloplume

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.

Deplete

Apparently, at least according to the Netbeans developers, that is the proper usage of PHPDoc - @property is for "private, protected or non-existent variables", but as I pointed out in the bug report I created, Netbeans shouldn't be hinting of these variables outside of the class. – Calandra

Answer 3

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/

Constitutionally

Seems that the example class I put together above is almost precisely how the PHPDoc documentation lays out the usage of @property. I'll have to start looking to see if any of the Netbeans dev are aware of or care about this discrepancy. – Calandra