phpDocumentor

phpDocumentor

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.

En phpDocumentor la documentación se distribuye en bloques DocBlock. Estos bloques siempre se colocan justo antes del elemento al que documentan y su formato es:

/**

* 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()

{

  ...

} 

Dentro de un bloque se pueden incluir marcas que serán interpretadas por phpDocumentor de forma especial.

Hay una serie de marcas estándar que pueden ir dentro de todos los DocBlock:

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

Declaración de funciones (elemento function)

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

Variables de clase (atributos)

Marca	Significado
@var	Documenta los atributos de la clase. Formato: * @var tipo comentario

Instalar phpDocumentor

Con PEAR instalado, ejecutar los siguientes comandos:

pear channel-discover pear.phpdoc.org
pear install phpdoc/phpDocumentor

Una vez que la instalación este completa, la función global, phpdoc, estara habilitada para su llamada.

Generar la documentación

phpDocumentor permite generar la documentación de varias formas y en varios formatos.

Opciones para generar documentación:

1. Desde línea de comandos (php CLI - Command Line Interpreter)
2. Desde interfaz web (incluida en la distribución)
3. Desde código. Como phpDocumentor está desarrollado en PHP, podemos incluir su funcionalidad dentro de scritps propios.

¿Qué hay que especificar?

1. El directorio en el que se encuentra nuestro código. phpDocumentor se encarga de recorrer los subdirectorios de forma automática
2. Opcionalmente los paquetes (@pakage) que deseamos documentar, lista de ficheros incluidos y/o excluidos y otras opciones interesantes para personalizar la documentación.
3. El directorio en el que se generará la documentación
4. Si la documentación va a ser pública (sólo interfaz) o interna (en este caso aparecerán los bloques private y los comentarios @internal).
5. El formato de salida de la documentación

Formatos de salida

1. HTML a través de un buen número de plantillas predefinidas (podemos definir nuestra propia plantilla de salida)
2. PDF
3. XML (DocBook). Muy interesante puesto que a partir de este dialecto podemos transformar (XSLT) a cualquier otro utilizando nuestras propias reglas y hojas de estilo.

Vamos a explicar cada etiqueta una a una 

@api

La etiqueta api se utiliza para declarar elementos estructurales para el uso por parte de terceros.

  /**
  * Este método no cambiará hasta un lanzamiento importante.  *
  * @api
  *
  * @return void
  */
  function showVersion()
  {
  <...>
  }

Mas información en: http://www.phpdoc.org/