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

79

У мене є такий код:

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

Я не вважаю, що використання @varправильне для константи, і я не бачу жодного @constantтегу PHPDoc. Як правильно це зробити?

php phpdoc

— Ельцо Валугі
джерело

Наскільки defineстурбований: stackoverflow.com/questions/2192751 / ...

— hakre

Я побачив, що дефініція - це окремі константи, я шукаю константу класу

— Ельцо Валугі,

1

можливий дублікат документації щодо констант класу

— phpDoc

@Elzo також const FOO = 1;працює поза контекстом класу.

— Гордон,

цей хлопець використовує @access private icosaedro.it/phplint/phpdoc.html , але мені невідомий той факт, що ви можете обмежити видимість для констант

— Ельцо Валугі,

-19

Щоб отримати їх у phpDoc, використовуйте:

@const THING

Звичайна конструкція:

@const[ant] label [description]

— Брайан
джерело

хіба різниця між константами класу та глобальними константами, ініційована дефініцією ()? Я здогадуюсь @const для позначення останнього.

— Січень

2

Це колишнє. Я щойно задокументував константу класу, і мої згенеровані phpdocs правильно містять опис. А станом на квітень 2017 року англійські документи все ще відсутні @const!

— Кіт,

2

@constнедійсний і не існує в PHPDocumentor. Використовуйте @var.

— Вейд,

151

PHP-FIG пропонує використовувати @varдля констант.

7.22. @var

Ви можете використовувати @varтег для документування "Тип" наступних "Структурних елементів":

Константи як класу, так і глобального масштабу

Властивості

Змінні, як глобального, так і локального масштабу

Синтаксис

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

— користувач2983026
джерело

1

То що, по суті, є коротким для "змінної", яку ми використовуємо для документування чогось, що є "постійним"?

— ankr

2

станом на 2017 рік використання @constбуде правильно виводити мій опис, але @varне буде виводити нічого для константи класу.

— Кіт,

Це застаріло. У поточній версії проекту PSR-5 про це більше не йдеться. Я стверджую , що константи не потрібен тип конкретний натяк , тому що їх тип незмінний і завжди може бути виведено: stackoverflow.com/a/50945077/752110

— Yogarine

122

@constце не правильна відповідь.

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

Єдине "офіційне" місце в списку - phpdoc.de, але специфікація там колись досягла 1,0 бета, а на сайті також є теги типу @brotherі @sister, які я ніколи раніше не бачив, тому загальна довіра до цього сайту дещо зменшено ;-) Фактичним стандартом завжди був phpDoc.org.

Коротше кажучи, навіть якщо якийсь неофіційний стандарт це згадує, якщо генератори документації не підтримують це, тоді не варто використовувати.

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

— Гері Дж
джерело

6

Врешті-решт, @typeбув відхилений на користь@var .

— вихід

1

Насправді це не має значення для IDE, наприклад, PHPStorm, наприклад, завжди бере фактичне значення коду, щоб з’ясувати тип (оскільки йому повинно бути присвоєне значення).

— позначка

3

Я використовую Netbeans. Він буде аналізувати phpDoc для глобальних констант та класів, коли використовується цей формат:

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

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

— Сонні
джерело

1

Чи не можете ви залишити @constпоза увагою константи класу в Netbeans?

— hakre

4

Я щойно протестував у Netbeans 8 і зміг опустити @constдля глобальних і класичних константних оголошень.

— Sonny

3

Немає необхідності коментувати тип констант, оскільки тип завжди:

або скаляр, або масив
відомий на момент декларування
незмінний

@constтакож не є частиною стандарту PHPDoc. PHP-FIG пропонує, @varале це не підтримується PHPDoc і не додає жодної інформації, яку ви вже не можете вивести з самої декларації.

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

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

Тут буде описано константу, коли ви створюєте PHPDocs, але зберігає коментарі чистими та читабельними.

— Йогарин
джерело

2

Наступна пропозиція відповідає синтаксису офіційної документації :

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

}

— Квадз
джерело