为常量编写PHPDocs的正确方法是什么？

Question

我有这个代码:

/**
 * Days to parse
 * @var int
 */
const DAYS_TO_PARSE = 10;
...

我不认为使用@var对于常量是正确的,我没有看到任何@constantPHPDoc标记.这样做的正确方法是什么？

Answer 1

PHP-FIG建议使用@var常量.

7.22. @var

您可以使用@var标签记录以下"结构元素"的"类型":

• 常量,包括类和全局范围
• 属性
• 变量,包括全局和局部范围

句法

@var ["Type"] [element_name] [<description>]

Answer 2

@const是不是正确的答案.

• 它不是遗留的phpDocumentor文档的一部分:http://manual.phpdoc.org/HTMLframesConverter/default/
• 它不是当前phpDocumentor文档的一部分:http://www.phpdoc.org/docs/latest/index.html
• 它没有列在维基百科上的标签列表中:http://en.wikipedia.org/wiki/PHPDoc#Tags
• 它没有在PHP-FIG草案PSR中列出:https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#7-tags

它的上市唯一的"官方"的地方是phpdoc.de,但该规范仅以往任何时候都作出1.0beta,并且该网站还包括像标签@brother,并@sister在该网站上,这是我以前从来没见过用,所以整体信任有点减少;-)事实上的标准一直是phpDoc.org.

简而言之,即使某些非官方标准确实提到它,如果文档生成器不支持它,那么它也不值得使用.

@var 是正确的 现在,一旦PSR(上面列表中的最后一个链接)没有草稿,并且是phpDocumentor,Doxygen,APIGen和其他人正在理解PHPDoc的基础,那么@type将是正确的,这是继承者@var.

Answer 3

不需要注释常量的类型，因为类型总是：

• 标量或数组
• 申报时已知
• 不可变的

@const也不是 PHPDoc 标准的一部分。PHP-FIG 建议，@var但这不受 PHPDoc 的支持，并且不会添加您无法从声明本身推断出的任何信息。

因此，为了可读性，我建议只使用一个普通的 PHPDoc 文档块来记录你的常量：

class Foo
{
    /**
     * This is a constant.
     */
    const BAR = 'bar';
}

它将在您生成 PHPDocs 时描述常量，同时保持注释干净和可读。

Answer 4

要将它们放入 phpDoc，请使用：

@const THING

常用构造：

@const[ant] label [description]