Как правильно написать PHPDocs для констант? - PullRequest
69 голосов
/ 15 июля 2011

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

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

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

Ответы [ 6 ]

116 голосов
/ 05 января 2015

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

7,22. @var

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

  • Константы как класса, так и глобальной области видимости
  • Свойства
  • Переменные, как глобальные, так и локальные области действия

Синтаксис

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

115 голосов
/ 26 августа 2013

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

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

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

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

2 голосов
/ 07 сентября 2017

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

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

}
2 голосов
/ 04 июня 2014

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

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

class MyClass
{
    /** @const Class constant description */
    const MY_CONST = 10;
}
0 голосов
/ 20 июня 2018

Нет необходимости комментировать тип констант, так как тип всегда:

  • скаляр или массив
  • известно во время объявления
  • неизменное

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

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

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

Он будет описывать константу, когда вы генерируете PHPDocs, но сохраняете комментарии чистыми и читаемыми.

0 голосов
/ 15 июля 2011

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

@const THING

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

@const[ant] label [description]
...