What is the correct way to write PHPDocs for constants?

user_95353 0
Viewed 45908

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?

phpdoc php
6 Answers

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.

user_7521100
Related