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

Posted 2023-02-22

【中文标题】为常量编写 PHPDocs 的正确方法是啥？

【英文标题】：What is the correct way to write PHPDocs for constants?为常量编写 PHPDocs 的正确方法是什么？

【发布时间】：2011-10-06 01:41:08

【问题描述】：

我有这个代码：

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

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

【问题讨论】：

就define而言：***.com/questions/2192751/…

我看到了，define是独立的常量，我在找一个类常量

phpDoc class constants documentation的可能重复

@Elzo const FOO = 1; 也适用于类上下文之外。

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

【参考方案1】：

The PHP-FIG suggests using @var for constants.

7.22。 @var

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

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

语法

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

【讨论】：

那么，我们用来记录“恒定”事物的“变量”本质上是什么？

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

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

@Yogarine 常量可能不需要类型提示，但可能需要记录常量的用途

@BradKent 当然。在这种情况下，只需添加一个没有任何注释的文档块就足够了。

【参考方案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 的基础，那么 @ 987654330@ 是正确的，它是@var 的继任者。

【讨论】：

最终，@type was dropped in favor of @var.

事实上，对于 IDE 来说这似乎并不重要，例如 PHPStorm 总是使用实际的代码值来找出类型（因为它必须分配一个值）。

【参考方案3】：

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

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

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

因此，为了便于阅读，我建议只使用普通的 PHPDoc 文档块来记录您的常量：

class Foo

    /**
     * This is a constant.
     */
    const BAR = 'bar';

它会在您生成 PHPDocs 时描述常量，同时保持 cmets 的清洁和可读性。

【参考方案4】：

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

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

class MyClass

    /** @const Class constant description */
    const MY_CONST = 10;

【讨论】：

你不能把@const留给Netbeans中的类常量吗？

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

在我的例子中，我添加了“/** 类常量描述 */”并且它起作用了。

【参考方案5】：

以下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";

【参考方案6】：

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

@const THING

通常的构造：

@const[ant] label [description]

【讨论】：

define() 发起的类常量和全局常量的区别不是吗？我猜@const 是用来标注后者的。

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

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