在 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->i，自动完成将列出两个 $id 属性：一个在我的 PHPDoc 中描述，另一个被描述为“未找到 PHPDoc”的未知变量。

有一个解决方案可以解决 Netbeans 问题 - 在每个属性上方添加一个 @var PHPDoc 块，但是我认为它不必要地弄乱了我的课程，尤其是我的一些具有 10 多个属性的课程。

对于我的两个问题（干净的文档、正确的 Netbeans 提示）是否有 [好的] 解决方案，还是我的处理不正确？

Answer 1

“property”标签是专门针对“magic”属性的，意思是那些实际上并没有出现在代码本身中的属性。这就是为什么标签只出现在类文档块中的关键原因。因此，我猜测识别“属性”标签的 IDE 是从“它在代码中看不到”的角度这样做的。诚然，我可以理解这样一种期望，即自动完成应该识别出这样一个属性的存在，并因此为您提供它。但是，我敢打赌，IDE 将坚持只使用代码本身来构建模型，并且只使用 docblock 信息来补充它已经在代码中看到的元素。

使用“var”标签是记录“编码”属性的一种正确方法。如果您想尽量减少在所有属性上使用该标签所需的行数，请使用单行文档块：

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

另外，您可以使用 docblock 模板来减少标签相似性适合您的代码的 docblock：

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

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

在这个简短的列表中，这似乎并没有多少节省，但当有很多属性时，它确实有帮助。此外，它在方法周围也能正常工作。

Answer 2

我更喜欢在每个属性上方使用@var，根本不使用@property。我觉得这使您可以更紧密地将 cmets 与正在评论的事物联系起来。即，一个属性的 cmets 总是紧挨着该属性。如果您使用@property 样式并且您有一个包含大量属性的大类，那么描述属性的注释完全有可能与它相距甚远。

Answer 3

我不确定确切的语法，但我确信 netbeans 会遵守标准的 php 文档。

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