phpDocumentor – organiza tu documentación PHP y expórtala a HTML

Existen algunas herramientas que permiten generar documentación de forma automática a partir del código fuente. Javadoc es la herramienta estándar en Java. Para PHP una de las herramientas más utilizadas es phpDocumentor.
La documentación de un proyecto de software es tan importante como su código. Una buena documentación nos facilita en gran medida el mantenimiento futuro de la aplicación. Si además estamos trabajando en equipo es muy útil saber lo que hacen las partes que desarrollan otras personas, sobretodo si tenemos que utilizarlas en nuestra parte.
Para ayudarnos existe la aplicación PhpDocumentor, que nos permite generar automáticamente una buena documentación de nuestro código, de una forma parecida a como lo hace JavaDoc. Mediante comentarios y unas etiquetas especiales podemos definir de forma sencilla que hace cada clase, cada método y cada función de nuestro código.

Los elementos que pueden ser documentados son:

• define
• function
• class
• class vars
• include/require/include_once/require_once
• global variables

/** * Descripción breve (una línea) * * Descripción extensa. Todas las líneas que * sean necesarias * Todas las líneas comienzan con * <- Esta línea es ignorada * * Este DocBlock documenta la función suma() */ function suma() { ... }

1 2 3 4 5 6 7 8 9 10 11 12 13 14

/** * Descripción breve (una línea) * * Descripción extensa. Todas las líneas que * sean necesarias * Todas las líneas comienzan con * <- Esta línea es ignorada * * Este DocBlock documenta la función suma() */ function suma() { ... }

Además se puede incluir documentación global a nivel de fichero y clase mediante la marca @package

Documentación para classes y archivos

Marca	Significado
@access	Si @access es ‘private’ no se genera documentación para el elemento (a menos que se indique explícitamente). Muy interesante si sólo se desea generar documentación sobre la interfaz (métodos públicos) pero no sobre la implementación (métodos privados).
@author	Autor del código
@copyright	Información sobre derechos
@deprecated	Para indicar que el elemento no debería utilizarse, ya que en futuras versiones podría no estar disponible.
@example	Permite especificar la ruta hasta un fichero con código PHP. phpDocumentor se encarga de mostrar el código resaltado (syntax-highlighted).
@ignore	Evita que phpDocumentor documente un determinado elemento.
@internal inline {@internal}}	Para incluir información que no debería aparecer en la documentación pública, pero sí puede estar disponible como documentación interna para desarrolladores.
@link inline {@link}	Para incluir un enlace (http://…) a un determinado recurso.
@see	Se utiliza para crear enlaces internos (enlaces a la documentación de un elemento).
@since	Permite indicar que el elemento está disponible desde una determinada versión del paquete o distribución.
@version	Versión actual del elemento

Dejo aquí un ejemplo

1

2 3 4 5 6 7 8 9 10 11 12 13 14 15

/** * Debug *  Gestión de los errores de php, logs de informacion etc... * * @package debug * @author Garretus * @copyright Garretus * @version 2.1 * @access public */ class Debug{ . . . }//END CLASS

Documentación para funciones y métodos

Marca	Significado
@global	Permite especificar el uso de variables globales dentro de la función.
@param	Parámetros que recibe la función. Formato: * @param tipo $nombre_var comentario
@return	Valor devuelto por la función. Formato: * @return tipo comentario

Ejemplo :

1

2 3 4 5 6 7 8 9 10 11 12 13 14

/**      * test to see if valid cache exists for this template      *      * @param string $tpl_file name of template file      * @param string $cache_id      * @param string $compile_id      * @return string|false results of {@link _read_cache_file()}      */     function is_cached($tpl_file, $cache_id = null, $compile_id = null)     {      .      .      .      }//END FUNCTION

Para terminar este post decir que mi IDE favorito PHPDesigner está perfectamente integrado con PHPDocumentor tanto para documentar como para compilar la documentación. Esta es una de las razones por las que es mi IDE favorito.