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提示），或者我是否在错误的方法上进行操作？

- Mattygabe

Answer 1

“property”标签专门用于“魔术”属性，即任何在代码本身中并未出现的属性。这也是该标签仅出现在类docblock中的关键原因。因此，我猜测识别“property”标签的IDE是从“它在代码中不可见”的角度来进行的。当然，我可以理解自动完成应该识别这种属性的存在，并因此使其可用。但是，我的赌注是IDE将坚持仅使用代码本身来构建模型，并仅使用docblock信息来补充已经在代码中看到的元素。

使用“var”标签是记录您的“编码”属性的一种正确方法。如果您想要最小化使用该标签对所有属性所需的行数，请使用单行docblock：

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

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

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

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

在这个简短的列表中，看起来节省不了多少，但在有很多属性时确实会有帮助。此外，在方法周围使用它也可以正常工作。

- ashnazg

---

不知道docblock模板 - 虽然我偶尔需要提供有关变量使用的额外注释，但这应该可以帮助我在保持代码文档化的同时保持自动完成的完整性。谢谢！ - Mattygabe

您可以将文档块模板与实际文档块结合使用，从而使模板信息“附加”到各个单独的文档块中。在上面的示例中，您仍然可以在$id和$number上放置特定的文档块，并提供其他信息而不是共享的var标签。在生成的文档中，两个变量都会捕获int数据类型。 - ashnazg

Answer 2

我更喜欢在每个属性上方使用 @var，而不使用 @property。我认为这样可以更紧密地将注释与被注释的内容关联起来。也就是说，属性的注释总是紧挨着属性。如果你使用 @property 风格，并且有一个具有大量属性的类，那么描述属性的注释可能会距离属性几页之远。

- Alex Howansky

---

显然，至少根据Netbeans开发人员的说法，这是PHPDoc的正确用法 - @property用于“私有、受保护或不存在的变量”，但正如我在创建的错误报告中指出的那样，Netbeans不应该在类外提示这些变量。 - Mattygabe

Answer 3

我不确定确切的语法，但我相信NetBeans会遵循标准的PHP文档。

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

- udnisap

---

看起来我上面组合的示例类几乎精确地展示了PHPDoc文档中@property的用法。我得开始寻找是否有Netbeans开发人员意识到或关心这种差异。 - Mattygabe