What is the correct way to write PHPDocs for constants?

Question

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?

Answer 1

To get them into phpDoc, use:

@const THING

Usual construct:

@const[ant] label [description]

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

Answer 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.

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

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

}

Answer 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.