Quelle est la manière correcte d'écrire des PHPDocs pour les constantes ?

Question

J'ai ce code :

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

Je ne pense pas qu'utiliser @var est correcte pour une constante et je ne vois aucune @constant Tag PHPDoc. Quelle est la bonne façon de procéder ?

Answer 1

Le PHP-FIG suggère d'utiliser @var pour les constantes.

7.22. @var

Vous pouvez utiliser le @var pour documenter le "Type" des éléments suivants "Éléments structurels" :

• Constantes, à la fois de classe et globales
• Propriétés
• Variables, à portée globale et locale

Syntaxe

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

Answer 2

@const es no la bonne réponse.

• Il ne fait pas partie de l'ancienne documentation de phpDocumentor : http://manual.phpdoc.org/HTMLframesConverter/default/
• Cela ne fait pas partie de la documentation actuelle de phpDocumentor : http://www.phpdoc.org/docs/latest/index.html
• Il n'est pas répertorié dans la liste des tags sur Wikipedia : http://en.wikipedia.org/wiki/PHPDoc#Tags
• Il ne figure pas dans le projet de RSP du PHP-FIG : https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#7-tags

Le seul endroit "officiel" où il est répertorié est phpdoc.de, mais la spécification n'est parvenue qu'à la version 1.0beta, et le site comprend également des balises telles que @brother y @sister que je n'ai jamais vu utilisé auparavant, donc la confiance globale dans ce site est quelque peu diminuée ;-) Le standard de facto standard a toujours été phpDoc.org.

En bref, même si une norme non officielle le mentionne, si les générateurs de documentation ne le prennent pas en charge, il n'y a pas lieu de l'utiliser.

@var est correct pour l'instant, et une fois que le PSR (dernier lien dans la liste ci-dessus) sera sorti de l'état de projet, et sera la base sur laquelle phpDocumentor, Doxygen, APIGen et d'autres comprennent PHPDoc, alors @type serait correcte qui est le successeur de @var .

Answer 3

Il n'y a pas besoin d'annoter le type des constantes, puisque le type est toujours :

• soit un scalaire ou un tableau
• connu au moment de la déclaration
• immuable

@const ne fait pas non plus partie de la norme PHPDoc. PHP-FIG suggère @var mais cela n'est pas soutenu par PHPDoc et n'ajoute aucune information que vous ne pouvez pas déjà déduire de la déclaration elle-même.

Par conséquent, pour des raisons de lisibilité, je recommande d'utiliser un simple docblock PHPDoc pour documenter vos constantes :

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

Il décrira la constante lorsque vous générerez les PHPDocs tout en gardant les commentaires propres et lisibles.

Answer 4

J'utilise Netbeans. Il analysera phpDoc pour les constantes globales et de classe lorsque ce format est utilisé :

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

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

Answer 5

Les éléments suivants proposition respecte la syntaxe de la documentation officielle :

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

}