Existen algunas herramientas que permiten generar documentación de forma automática a partir del código fuente, Javadoc es la herramienta estándar para Java, para PHP una de las herramientas más utilizadas es phpDocumentor.

Como ya comentamos antes, 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, sobre todo 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 cómo lo hace JavaDoc. Mediante comentarios y unas etiquetas especiales podemos definir de forma sencilla qué hace cada clase, cada método y cada función de nuestro código. Para saber más sobre esta aplicación se puede acceder a su página web, desde donde se puede descargar la aplicación (es software libre) y acceder a la documentación de ésta, de todas maneras intentaremos ampliar aquí los conocimientos sobre esta herramienta.

phpDocumentor

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

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

En todo caso, es necesario especificar los siguientes parámetros:

1. El directorio en el que se encuentra nuestro código. PhpDocumentor se encargará luego 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.

Una alternativa a phpDocumentor es Doxygen que puede también documentar código PHP, la principal diferencia es que Doxygen es un programa, mientras phpDocumentor es una colección de código en PHP. Es decir, genera la documentación con el mismo PHP usado para ejecutar el propio código PHP, es por ello que se necesita tener también PHP instalado, sin embargo no se necesita instalar un servidor web.