Question

我有这段代码：

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

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

Answer 1

@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 2

The PHP-FIG suggests using @var for constants.

7.22。 @var

您可以使用@var标记来记录＆＃34;类型＆＃34;以下的   ＆＃34;结构要素＆＃34;：


常量，包括类和全局范围

属性

变量，包括全局和本地范围


语法

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

Answer 3

我使用Netbeans。当使用这种格式时，它将解析phpDoc的全局和类常量：

/** @const Global constant description */
define('MY_CONST', 10);

class MyClass
{
    /** @const Class constant description */
    const MY_CONST = 10;
}

Answer 4

以下proposition尊重the official documentation syntax：

class Foo
{
    const
        /**
         * @var string Should contain a description
         */
        MY_CONST1 = "1",
        /**
         * @var string Should contain a description
         */
        MY_CONST2 = "2";

}

Answer 5

由于类型始终为：

，因此无需注释常量的类型。

标量或数组
在声明时已知
不可变

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

因此，出于可读性考虑，我建议仅使用普通的PHPDoc文档块来记录您的常量：

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

它将在生成PHPDocs时描述常量，同时保持注释的清晰可读。

Answer 6

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

@const THING

通常的构造：

@const[ant] label [description]

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

6 个答案: