web-dev-qa-db-fra.com

Quelle est la bonne façon d'écrire PHPDocs pour les constantes?

J'ai ce code:

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

Je ne pense pas que l'utilisation de @var est correct pour une constante et je n'en vois pas @constant Balise PHPDoc. Quelle est la bonne façon de procéder?

phpphpdoc
69
Elzo Valugi

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

7.22. @var

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

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

Syntaxe

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

122
user2983026

@const n'est pas la bonne réponse.

Le seul endroit "officiel" dans lequel il est répertorié est phpdoc.de, mais les spécifications ne sont jamais parvenues à 1.0beta, et le site comprend également des balises comme @brother et @sister, que je n'ai jamais vu utilisé auparavant, donc la confiance globale dans ce site est quelque peu diminuée ;-) La norme de facto 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, cela ne vaut pas la peine d'être utilisé.

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

117
GaryJ

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;
}
2
Sonny

Ce qui suit proposition respecte la syntaxe de documentation officielle :

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

}
2
Kwadz

Il n'est pas nécessaire d'annoter le type de constantes, car 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 du standard PHPDoc. PHP-FIG suggère @var mais ceci 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 simplement d'utiliser un docblock PHPDoc simple pour documenter vos constantes:

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

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

0
Yogarine