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

What is the correct way to write PHPDocs for constants?

提问by Elzo Valugi

I have this code:

我有这个代码：

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

I don't think that using @varis correct for a constant and I don't see any @constantPHPDoc tag. What is the correct way to do this?

我不认为使用@var常量是正确的，而且我没有看到任何@constantPHPDoc 标签。这样做的正确方法是什么？

采纳答案by Brian

To get them into phpDoc, use:

要让它们进入 phpDoc，请使用：

@const THING

Usual construct:

通常的构造：

@const[ant] label [description]

回答by user2983026

The PHP-FIG suggests using @varfor constants.

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

7.22. @var

You may use the @vartag to document the "Type" of the following "Structural Elements":

• Constants, both class and global scope
• Properties
• Variables, both global and local scope

Syntax

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

7.22. @var

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

• 常量，包括类和全局作用域
• 特性
• 变量，全局和局部范围

句法

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

回答by GaryJ

@constis notthe right answer.

@const是不是正确的答案。

• It's not part of the legacy phpDocumentor docs: http://manual.phpdoc.org/HTMLframesConverter/default/
• It's not part of the current phpDocumentor docs: http://www.phpdoc.org/docs/latest/index.html
• It's not listed in the list of tags on Wikipedia: http://en.wikipedia.org/wiki/PHPDoc#Tags
• It's not listed in the PHP-FIG draft PSR: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#7-tags

• 它不是旧版 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

The only "official" place it's listed is phpdoc.de, but the spec there only ever made it to 1.0beta, and the site also includes tags like @brotherand @sister, which I've never seen used before, so the overall trust in that site is somewhat diminished ;-) The de facto standard has always been phpDoc.org.

它列出的唯一“官方”位置是 phpdoc.de，但那里的规范只发布到 1.0beta，并且该站点还包括像@brotherand 之类的标签@sister，我以前从未见过使用过，因此对该站点的总体信任有所减少;-) 事实上的标准一直是 phpDoc.org。

In short, even if some unofficial standard does mention it, if the documentation generators don't support it, then it's not worth using.

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

@varis correct for now, and once the PSR (last link in the above list) is out of draft, and is the basis for which phpDocumentor, Doxygen, APIGen and others are understanding PHPDoc, then @typewould be correct which is the successor to @var.

@var是正确的 就目前而言，一旦 PSR（上面列表中的最后一个链接）未起草，并且是 phpDocumentor、Doxygen、APIGen 和其他人理解 PHPDoc 的基础，那么@type哪个是继任者就正确了@var.

回答by Yogarine

There is no need to annotate the type of constants, since the type is always:

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

• either a scalar or an array
• known at declaration time
• immutable

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

@constis also not part of the PHPDoc standard. PHP-FIG suggests @varbut this is not backed by PHPDoc and doesn't add any information you can't already deduce from the declaration itself.

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

Therefore, for the sake of readability I recommend just using a plain PHPDoc docblock to document your constants:

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

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

It will describe the constant when you generate PHPDocs yet keeps the comments clean and readable.

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

回答by Kwadz

The following propositionrespects 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";

}

回答by Sonny

I use Netbeans. It will parse phpDoc for global and class constants when this format is used:

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

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

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