在Netbeans PHP中记录类的正确方法

Question

为了便于维护和IDE类自动完成和成员提示,我在我的项目中使用了PHPDoc.鉴于此示例类:

class my_class {
    public $id;
    public $name;
    public $number;

    public function __construct() {
        //Do something
    }

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

我更愿意用类文档本身记录所有属性($id,$name和$number),它们在类声明之上,然后在每个方法上面放置方法文档(如果需要).这是我最终希望我的班级看起来像:

/**
 * 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;
    }
}

这正是我更喜欢的文档,但Netbeans的自动完成无法正常运行,因为它列出了每个属性两次.例如,如果我开始输入$my_class_object->iauto-complete将列出两个$ id属性:一个如我的PHPDoc中所述,另一个被描述为带有"PHPDoc Not Found"的未知变量.

有一个解决方案可以解决Netbeans问题 - @var在每个属性上面添加一个PHPDoc块,但是我认为它不必要地使我的类变得混乱,特别是我的一些具有10多个属性的类.

对我的两个问题(干净的文档,正确的Netbeans暗示)是否有[好]解决方案,或者我是否正确地解决了这个问题？

Answer 1

"property"标签专门用于"魔术"属性,这意味着任何实际上不会出现在代码本身中的属性.这是标签仅在类docblock中出现的关键原因.因此,我猜测识别"属性"标签的IDE是这样做的,"从代码中看不出来".当然,我可以理解一种期望,即自动完成应该识别这种属性的存在,从而使它可供您使用.但是,我敢打赌,IDE将坚持只使用代码本身来构建模型,并且只使用docblock信息来补充它已经在代码中看到的元素.

使用"var"标签是记录"编码"属性的正确方法.如果要最小化为在所有属性上使用该标记所需的行,请使用单行docblock:

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

此外,您可以使用docblock模板来减少docblock,其中标记相似性适合您的代码:

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

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

这个短名单似乎并没有多少节省,但是当有很多属性时它会有所帮助.此外,它适用于各种方法.