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

@const es no la respuesta correcta.

• No es parte del legado phpDocumentor docs: http://manual.phpdoc.org/HTMLframesConverter/default /
• No es parte de los documentos actuales de phpDocumentor: http://www.phpdoc.org/docs/latest/index.html
• No está en la lista de etiquetas de Wikipedia: http://en.wikipedia.org/wiki/PHPDoc#Tags
• No aparece en el borrador 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 allí solo llegó a 1.0 beta, y el sitio también incluye etiquetas como @brother y @sister, que nunca he visto usar antes, por lo que la confianza general en ese sitio se ve algo disminuida ; -) El de facto estándar siempre ha sido phpDoc.org.

En resumen, incluso si algún estándar no oficial lo menciona, si el los generadores de documentación no lo soportan, 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 para la cual phpDocumentor, Doxygen, APIGen y otros están entendiendo PHPDoc, entonces @type sería correcto, que es el sucesor de @var.

El PHP-FIG sugiere usar @var para constantes.

7.22. @var

Puede usar la etiqueta @var para documentar el "Tipo" de lo siguiente "Elementos Estructurales":

• Constantes, tanto de clase como de alcance global
• Propiedades
• Variables, tanto de alcance global como local

Sintaxis

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

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

La siguiente proposición 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";

}

No hay necesidad de escribir constantes, ya que el tipo de la constante es siempre 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 esto no es usado por PHPDoc y no agrega ninguna información que no pueda deducir de la propia declaración.

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

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