Otro Blog Más

En una entrada anterior se mostró como configurar un proyecto en Subversion para completar el PHPDocumentor, pero no se entró en muchos detalles del PHPDocumentor. Esta guía pretende adentrarse un poco más en esta herramienta que ayuda a generar documentación de un proyecto hecho en PHP.

Existen tres tipos de documentaciones:

• Interfaz (para los usuarios del código): qué hace, como se utiliza, que devuelve, … Pero no cómo lo hace.
• Implementación (para editores del código): cómo funciona internamente, que algoritmos utiliza, …
• Toma de decisiones (para editores y responsables de desarrollo): por qué se ha implementado de una forma o otra (razones de rendimiento, recursos, …).

La documentación de la implementación reside dentro del código, y la de la interfaz ha de ser un documento. Pues PHPDocumentor se encarga de convertir la documentación que existe en el código, a documentación legible desde un documento como una página web. De esta forma, cada vez que se aplique un cambio en el código, esto repercutirá en la documentación de la interfaz, manteniendola actualizada constantemente.

Para conseguir esto, la documentación en el código tiene que seguir unos estándares. Se escriben unos bloques de documentación llamados DocBlock, que siguen una estructura y pueden tener una serie de marcas para ayudar a PHPDocumentor a entender mejor la documentación. Un ejemplo de bloque DocBlock de una función seria:

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

Se puede comentar cualquier archivo PHP (.php, .php5, .phtml), y dentro de ellos se pueden documentar: clases, variables, defines, funciones, variables globales y llamadas a otros ficheros. En los DocBlock, unas de las muchas marcas que se pueden añadir son:

• @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: 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: 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

Marcas para funciones:

• @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

Marca para variables:

• @var: Documenta los atributos de la clase. Formato: @var tipo comentario

Tipos de datos:

• array
• string
• boolean
• integer
• float
• object
• mixe

Ejemplos:

/**
* Dirección de correo
* @var string
* @access protected
*/
protected$_email;
 
/**
* Verifica si una direccion de correo es correcta o no.
*
* @return boolean true si la direccion es correcta
* @param string $email direccion de correo
*/
function checkEmailAddress ($email)
{
....
}

Vía Epsiolon Eridani.

Entradas relacionadas:

1. Configurar proyecto en Subversion para completar PHPDocumentor
2. Función REMOVE para Array de Javascript
3. 10 claves para crear una aplicación web exitosa
4. Crear máquina virtual de desarrollo en VirtualBox
5. Configurar PHP para que muestre los errores