Proper Way to Document Class in Netbeans PHP

问题

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?

回答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.

回答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.

回答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/

来源：https://stackoverflow.com/questions/8990688/proper-way-to-document-class-in-netbeans-php