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

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

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

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

Ответ 1

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

@const THING

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

@const[ant] label [description]

Ответ 2

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

Это не часть устаревших документов phpDocumentor: http://manual.phpdoc.org/HTMLframesConverter/default/
Это не часть текущих документов phpDocumentor: http://www.phpdoc.org/docs/latest/index.html
Он не указан в списке тегов в Википедии: http://en.wikipedia.org/wiki/PHPDoc#Tags
Он не указан в проекте PHP-FIG PSR: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#7-tags

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

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

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

Ответ 3

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

7,22. @var

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

Константы, как класс, так и глобальная область

Свойства

Переменные, как глобальные, так и локальные.
Синтаксис

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

Ответ 4

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

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

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

Ответ 5

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

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

}

Ответ 6

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

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

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

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