What is the correct way to write PHPDocs for constants?

问题

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?

回答1:

To get them into phpDoc, use:

@const THING

Usual construct:

@const[ant] label [description]

回答2:

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>]

回答3:

@const is not the right answer.

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

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

回答4:

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

回答5:

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

}

回答6:

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.

来源：https://stackoverflow.com/questions/6706051/what-is-the-correct-way-to-write-phpdocs-for-constants

标签

php

phpdoc