¿Alguien me puede decir cuál es la forma correcta de definir espacios de nombres php en la sintaxis phpDoc? O, ¿está @package obsoleto en phpDoc, ya que los espacios de nombres definen más o menos un paquete?Definición de espacios de nombres en la sintaxis phpDoc
Si no hay ninguno, ¿existe una forma común de documentar los espacios de nombres en los que se encuentra un documento?
phpDoc no tiene un concepto de espacios de nombres, pero puede (y probablemente debería) usar @package para ello.
Puede echar un vistazo al phplint documentation para ver cómo están formateando los espacios de nombres.
@package Debería usarse en cada docblock de cada archivo en su proyecto, también puede usar @subpackage. @package no está en desuso, y sería la forma correcta de definir sus espacios de nombres.
Gracias, @subpackage podría ser de utilidad, sin embargo, esto no resuelve mi problema. +1 –
Puede echar un vistazo a DocBlox; este es un generador de documentación API que admite espacios de nombres.
Y para responder más claramente a su pregunta: en lo que he encontrado son paquetes considerados Desaprobados debido a la invención de espacios de nombres. Si lee la especificación PSR-0, verá que trata de proporcionar el paquete como segunda parte de un espacio de nombres; primero siendo vendedor.
La documentación phpDoc dice:
La etiqueta @package se puede utilizar como una contraparte o suplemento a espacios de nombres. Los espacios de nombres proporcionan una subdivisión funcional de Elementos estructurales donde la etiqueta @package puede proporcionar una subdivisión lógica en , de esta forma los elementos se pueden agrupar con una jerarquía diferente.
Si, en general, las subdivisiones lógicas y funcionales son IGUALMENTE NO SE RECOMIENDA usar la etiqueta @package, para evitar el gasto de mantenimiento de .
https://www.phpdoc.org/docs/latest/references/phpdoc/tags/package.html
Gracias por hacer referencia a una biblioteca existente que usa formato de espacio de nombres en su documentación. No pude encontrar uno, definitivamente útil. –
[Manual de PHPdoc] (http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html) es también un buen recurso –
Desde esta respuesta, las cosas se han movido un poco. phpDoc ahora usa mucho un concepto de espacio de nombres, pero la documentación de phpDoc no lo define, ya que es un concepto de lenguaje PHP que se vuelve controlable en PHP 5.3. La documentación de phpDoc ahora recomienda el uso de espacios de nombres sobre @package, donde la intención es tener la misma jerarquía en ambos, como suele ser el caso. – ClearCrescendo