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 Not Found”。

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

我的两个问题（干净的文档，正确的Netbeans暗示）是否有[好]解决方案，或者我是否错误地解决了这个问题？

Answer 1

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

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

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

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

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

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

在这个短名单中似乎没有多少节省，但是当有很多属性时它确实有帮助。此外，它适用于各种方法。

Answer 2

我更喜欢在每个属性上面使用@var，而根本不使用@property。我觉得这可以让你更紧密地将评论与评论的内容联系起来。也就是说，酒店的评论始终紧挨着酒店。如果您正在使用@property样式并且您拥有一个包含大量属性的大类，那么描述属性的注释完全可能是远离它的页面。

Answer 3

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

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

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

3 个答案: