Как правильно писать PHPDocs для констант?

у меня есть этот код:

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

Я не думаю, что использование @var правильно для константы, и я не вижу никаких @constant тег PHPDoc. Как правильно это сделать?

57
php phpdoc

6 ответов

чтобы получить их в phpDoc, использовать:

@const THING

обычная конструкция:

@const[ant] label [description]
-5

@const is не правильный ответ.

единственное "официальное" место в списке phpdoc.de, но спецификация там только когда-либо делала это до 1.0 beta, и сайт также включает теги, такие как @brother и @sister, который я никогда не видел раньше, поэтому общее доверие к этому сайту несколько уменьшилось ; -) де-факто стандарт всегда был phpDoc.org.

короче, даже если какой-то неофициальный стандарт упоминает об этом, если генераторы документации не поддерживают его, тогда его не стоит использовать.

@var правильно на данный момент, и как только PSR (последняя ссылка в приведенном выше списке) выходит из проекта и является основой, на которой phpDocumentor, Doxygen, APIGen и другие понимают PHPDoc, то @type было бы правильно, который является преемником @var.

102

PHP-FIG предлагает использовать @var для констант.

7.22. @var

можно использовать @var тег для документирования" типа " следующего "Структурные Элементы":

  • константы как класс, так и в мировом масштабе.
  • свойства
  • переменные, как глобальные, так и локальные рамки

синтаксис

@var ["Type"] [element_name] [<description>]

87

Я использую Netbeans. Он будет анализировать phpDoc для глобальных констант и констант классов при использовании этого формата:

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

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

следующее предложение уважение синтаксис официальной документации: 

class Foo
{
    const
        /**
         * @var string Should contain a description
         */
        MY_CONST1 = "1",
        /**
         * @var string Should contain a description
         */
        MY_CONST2 = "2";

}
2

нет необходимости вводить константы, так как тип константы всегда скалярный или массив, известный при объявлении и не может измениться.

@const также не является частью стандарта PHPDoc. PHP-FIG предлагает @var но это не используется PHPDoc и не добавляет никакой информации, которую вы еще не можете вывести из самого объявления.

поэтому для удобства чтения я рекомендую просто использовать простой PHPDoc docblock для документирования вашего константы:

class Foo
{
    /** This is a constant */
    const BAR = 'bar';
}
0