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

有一种解决方案可以解决Netbeans问题——在每个属性上方添加一个@var PHPDoc块，但我认为这不必要地混淆了我的类，尤其是我的一些具有10+属性的类。

我的这两个问题都有[好]的解决方案吗（干净的文档，正确的Netbeans暗示），还是我做得不对？

Answer 1

"property"标记是专门明确地用于"magic"属性的，意味着任何实际上没有出现在代码中的属性。这就是为什么标记只出现在类docblock中的关键原因。因此，我猜识别"property"标记的IDE是从"代码中看不到"的角度来识别的。当然，我可以理解这样一种期望，即自动完成应该承认这样一个财产的存在，并因此为您提供它。然而，我敢打赌，IDE将坚持只使用代码本身来构建模型，而只使用docblock信息来补充它在代码中已经看到的元素。

使用"var"标记是记录"编码"属性的一种正确方式。如果您想最小化在所有属性上使用该标签所需的行数，请使用单行文档块：

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

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

/** @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.htmlhttp://www.phpdoc.org/