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
De todos es sabido que es fundamental producir un código correctamente documentado.
¿Qué conviene documentar dentro del código?. Fundamentalmente tres cosas:Tipo de documentación | Información | A quién va dirigida |
La interfaz | Qué hace (no como lo hace) una función o un método de una clase.
Qué parámetros hay que pasar.
Qué devuelve.
Ejemplo de uso. | Esta información es útil para las personas que utilizan funciones o clases diseñadas por otros |
La implementación | Dentro de una función, cómo se lleva a cabo cada paso.
Por qué seutiliza esta variable y no aquella.
Qué algoritmo se utiliza.
Qué hacen los métodos privados de una clase. | Esta información sólo interesa a las personas que necesiten depurar o actualizar el bloque de código. |
La toma de decisiones | Por qué se ha implementado de una determinada forma y no de otra (p.e. por razones de rendimiento o por optimización de recursos, etc..). | Esta informacióninteresa tanto a nivel de implementación (desarrollador) como a nivel funcional (responsable de desarrollo). |
Normalmente la información sobre la implementación no necesita salir del código.
Por el contrario, la información de la interfaz conviene pasarla a un documento independiente del código fuente (manual de uso). La persona que necesite utilizar una determinada librería de clases o funcionestendrá toda la información necesaria: qué hace cada elemento y cómo se utiliza. No necesita acceder al código fuente.
El problema con este tipo de documentación es que cada vez que se modifica algo en el código (actualizaciones, corrección de errores, etc...) hay que reflejarlo también en el manual de uso... doble trabajo.
Lo ideal por tanto sería poder automatizar de alguna forma este proceso.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 (www.phpdoc.org).
El funcionamiento básico se representa en el siguiente esquema:

 
DocBlock
En phpDocumentor la documentación se distribuye en bloques DocBlock. Estosbloques 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()
{
  ...
}
Los elementos que pueden ser documentados son:
* define* function
* class
* class vars
* include/require/include_once/require_once
* global variables
Además se puede incluir documentación globlal a nivel de fichero y clase mediante la marca @package
 
Marcas (tags)
Dentro de un bloque DocBlock se pueden incluir marcas que serán interpretadas por phpDocumentor de forma especial.
Hay una serie de marcas estándar que pueden irdentro 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...