CODEWITHSUNDEEP
phpphpdoc
Elzo Valugi
Elzo Valugi

Reputation: 27886

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?

Upvotes: 97

Views: 54510

Answers (6)

Yogarine
Yogarine

Reputation: 414

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.

Upvotes: 8

Kwadz
Kwadz

Reputation: 2232

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

}

Upvotes: 3

GaryJ
GaryJ

Reputation: 1926

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

Upvotes: 133

user2983026
user2983026

Reputation: 1799

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

Upvotes: 170

Sonny
Sonny

Reputation: 8336

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

Upvotes: 4

Brian
Brian

Reputation: 8626

To get them into phpDoc, use:

@const THING

Usual construct:

@const[ant] label [description]

Upvotes: -23

Related Questions