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

我有这个密码:

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

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

46729 次浏览
小开
最佳答案

To get them into phpDoc, use:

@const THING

Usual construct:

@const[ant] label [description]
小开

@const is not the right answer.

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.

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

小开

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

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


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

The PHP-FIG suggests using @var for constants.

7.22. @var

You may use the @var tag 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>]

小开

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


}
小开

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

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

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

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.


提交答案