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

I have this code:

我有这段代码:

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

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

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

6 个解决方案

#1

-3

To get them into phpDoc, use:

要让他们进入phpDoc，请使用:

@const THING

Usual construct:

通常的构造:

@const[ant] label [description]

#2

100

@const is not the right answer.

@const不是正确答案。

It's not part of the legacy phpDocumentor docs: http://manual.phpdoc.org/HTMLframesConverter/default/
它不是遗留phpDocumentor文档的一部分:http://manu.phpdoc.org/htmlframesconverter/default/。
It's not part of the current phpDocumentor docs: http://www.phpdoc.org/docs/latest/index.html
它不是当前phpDocumentor文档的一部分: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
它没有在*的标签列表中列出:http://en.wikipedia.org/wiki/PHPDoc#标签
It's not listed in the PHP-FIG draft PSR: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#7-tags
PHP-FIG草案PSR中没有列出:https://github.com/phpdocumentor/fig-standards/blob/master/sed/phpdoc.md 7标签

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 @brother and @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.0测试版,和网站还包括标签如@brother和@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.

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

@var is 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 @type would be correct which is the successor to @var.

@var现在是正确的，一旦PSR(上面的列表中的最后一个链接)已经退出，并且是phpDocumentor, Doxygen, APIGen和其他人理解PHPDoc的基础，那么@type将是正确的，这是@var的继承。

#3

The PHP-FIG suggests using @var for constants.

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

7.22. @var

7.22。@var

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

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

Constants, both class and global scope

常量，类和全局范围。

Properties

属性

Variables, both global and local scope

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

Syntax

语法

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

@var[“类型”][element_name][ <描述> )

#4

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

}

#5

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;
}

#6

There is no need to type constants, since the type of the constant is always a scalar or array, known at declaration and can not change.

不需要输入常量，因为常量的类型总是标量或数组，在声明时已知，不能更改。

@const is also not part of the PHPDoc standard. PHP-FIG suggests @var but this is not used by PHPDoc and doesn't add any information you don't already can 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';
}

#1

-3