¿Cómo se usa @package & @subpackage en phpdoc?

Question

me pregunto cómo debo utilizar @package & @subpackage para doc clase.

Digamos que tengo la siguiente clase

class My_Controller_Action_Helper_MyHelperAction extends Foo_Bar {} 

Si fuese:

@category My 
@package  Controller 
@subpackage Action_Helper 

o

@category My 
@package  Controller 
@subpackage Action_Helper_MyHelperAction 

o

@category My 
@package  Controller_Action 
@subpackage MyHelperAction 

o

@category My 
@package My_Controller_Action 
@subpackage MyHelperAction 

¿Qué pasa si el uso de espacio de nombres en lugar de '_'?

Answer 1

Primero: si utiliza "_" o "\" (el separador de espacio de nombres) no debe influir en su decisión, cómo realizar anotaciones en las clases. El guión bajo "_" proviene de una edad anterior al espacio de nombres y "actúa como" el separador del espacio de nombres, excepto que no crea espacios de nombres. Por lo tanto, "My_Controller_Action" debe tratarse como "Acción" en "My_Controller".

Sin embargo, cómo usa @package y/o @subpackage es realmente su decisión. Por ejemplo, yo no uso @category en absoluto y @subpackage es todo después del "segundo" espacio de nombres. Me explico: sigo la norma PSR-0, donde un paquete está estructurado en \<Vendorname>\<packagename>\<subpackage>\... (o "_" en lugar de "\", dependiendo de la versión). Luego @package <vendorname>.<package> y @subpackage <subpackage>.

Conclusión: depende de usted :) Un documento o gerenate diferentes estructuras de su código, dependiendo de las etiquetas que utiliza y cómo los usa. Solo pruébalo.

Answer 2

uso @package para el nombre del paquete al que pertenece este archivo ... sorpresa :) por ejemplo, si se trata de un complemento llamado xyz el @package para todos los archivos que pertenecen a ese paquete.

para doxygen (que yo uso) no existe tal cosa como @subpackage aunque puede hacer la suya propia. por ejemplo: http://www.stack.nl/~dimitri/doxygen/commands.html

Para doxygen puede usar algo como my.awesome.package @package la que se descompone a 'paquetes' sub

Realmente se puede utilizar para cualquier cosa, siempre y cuando tenga sentido y es consistente. primero decida qué desea usar y luego mire las recomendaciones/documentos para esa aplicación, ya que son todos diferentes