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

78

我有这个代码：

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

我认为使用@var常数不正确，并且看不到任何@constantPHPDoc标记。正确的方法是什么？

php phpdoc

— 埃尔佐·瓦鲁吉（Elzo Valugi）
source

至于define而言：stackoverflow.com/questions/2192751/...

— hakre

我看到一个定义是针对独立常量的，我正在寻找一个类常量

— Elzo Valugi 2011年

1

phpDoc类常量文档的

— hakre，2011年

@Elzo也在const FOO = 1;类上下文之外工作。

— Gordon

这个家伙正在使用@access private icosaedro.it/phplint/phpdoc.html，但是我不知道您可以限制常量的可见性

— Elzo Valugi 2011年

-18

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

@const THING

通常的构造：

@const[ant] label [description]

— 布赖恩
source

类常量和由define（）初始化的全局常量之间有区别吗？我猜@const用于表示后者。

— 1

2

是前者。我只是记录了一个类常量，并且我生成的phpdocs正确包含了描述。截至2017年4月，英文文档仍然没有@const！

— 基思

2

@const无效，并且在PHPDocumentor中不存在。使用@var。

— 韦德

148

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

7.22。 @var

您可以使用@var标记来记录以下“结构元素”的“类型”：

常量，包括类和全局范围

物产

全局范围和局部范围的变量

句法

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

— 用户2983026
source

1

那么，用于记录“恒定”值的“变量”本质上是什么呢？

— ankr

2

截至2017年使用@const将正确输出我的描述，但@var不会为类常量输出任何内容。

— 基思

这已经过时了。PSR-5草案的当前版本不再具体提及这一点。我坚持认为常量不需要特定的类型提示，因为它们的类型是不可变的，并且可以随时推导：stackoverflow.com/a/50945077/752110

— Yogarine

122

@const是不是正确的答案。

它不是旧版phpDocumentor文档的一部分：http : //manual.phpdoc.org/HTMLframesConverter/default/
它不是当前phpDocumentor文档的一部分：http ://www.phpdoc.org/docs/latest/index.html
它未列在Wikipedia上的标签列表中：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~~。

— 加里
source

6

最终，@type被放弃了@var。

— outis

1

实际上，对于IDE来说似乎并不重要，例如，PHPStorm始终使用实际的代码值来找出类型（因为必须为其分配值）。

— 2016年

3

无需注释常量的类型，因为类型始终为：

标量或数组
在申报时知道
一成不变的

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

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

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

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

— 瑜珈
source

2

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

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

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

— 桑尼
source

1

您不能@const在Netbeans中省略类常量吗？

— hakre 2014年

4

我刚刚在Netbeans 8中进行了测试，并且能够省略@const全局和类常量声明。

— 桑尼2014年

2

以下命题尊重官方文档语法：

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

}

— 夸兹
source