example - ¿Cuál es la forma correcta de escribir PHPDocs para constantes?

phpdocumentor español

Question

Tengo este código:

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

No creo que usar @var sea ​​correcto para una constante y no veo ninguna etiqueta @constant PHPDoc. ¿Cuál es la forma correcta de hacer esto?

Answer 1

La siguiente proposition respeta la sintaxis de la documentación oficial :

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

Answer 2

No es necesario escribir constantes, ya que el tipo de la constante siempre es un escalar o matriz, conocido en la declaración y no puede cambiar.

@const tampoco forma parte del estándar PHPDoc. PHP-FIG sugiere @var pero PHPDoc no lo utiliza y no agrega ninguna información que no pueda deducir de la declaración en sí.

Por lo tanto, en aras de la legibilidad, recomiendo simplemente usar un simple docblock de PHPDoc para documentar sus constantes:

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

Answer 3

Para incorporarlos a phpDoc, use:

@const THING

Construcción usual:

@const[ant] label [description]

Answer 4

Yo uso Netbeans. Analizará phpDoc para constantes globales y de clase cuando se use este formato:

/** @const Global constant description */
define(''MY_CONST'', 10);
class MyClass
{
/** @const Class constant description */
const MY_CONST = 10;
}

Answer 5

El PHP-FIG sugiere usar @var para constantes.

7.22. @var

Puede usar la etiqueta @var para documentar el "Tipo" de los siguientes "Elementos estructurales":

• Constantes, alcance de clase y global
• Propiedades
• Variables, alcance global y local

Sintaxis

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

Answer 6

@const no es la respuesta correcta.

• No forma parte de los documentos heredados de phpDocumentor: http://manual.phpdoc.org/HTMLframesConverter/default/
• No forma parte de los documentos actuales de phpDocumentor: http://www.phpdoc.org/docs/latest/index.html
• No aparece en la lista de etiquetas en Wikipedia: http://en.wikipedia.org/wiki/PHPDoc#Tags
• No aparece en el borrador del PSR de PHP-FIG: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#7-tags

El único lugar "oficial" que aparece es phpdoc.de, pero la especificación solo llegó a 1.0 beta, y el sitio también incluye etiquetas como @brother y @sister , que nunca antes había visto, así que el general la confianza en ese sitio está algo disminuida ;-) El estándar de facto siempre ha sido phpDoc.org.

En resumen, incluso si algún estándar no oficial lo menciona, si los generadores de documentación no lo admiten, entonces no vale la pena usarlo.

@var es correcto por ahora, y una vez que el PSR (último enlace en la lista anterior) está fuera de borrador, y es la base por la cual phpDocumentor, Doxygen, APIGen y otros están entendiendo PHPDoc, entonces @type sería correcto, que es el sucesor de @var .