Generar documentación php con apigen 4.1

Conforme va creciendo una aplicación, se va complicando el manejo del proyecto, por ejemplo para que sirva cada clase, cada método, cada atributo, y no solo para el desarrollador, sino para todos los colaboradores  y así ellos puedan entender partes del código sin necesidad de analizar el código línea a línea.

El estándar de programación, define las reglas para escribir y documentar código, además de cómo se comunican las diferentes piezas de código desarrolladas por diferentes equipos. El objetivo de esto es que parezca que el código ha sido escrito por una única persona.
De allí la importancia de documentar el código.

¿Qué es PHPDoc?

Wikipedia dice: es una adaptación de javadoc para php que define un estándar oficial para comentar código php, con las siguientes características:

• Hace comentarios que pueda leerse en un método estándar para animar a los programadores a definir y comentar los aspectos del código que normalmente se ignoran.

• Permite que los generadores de documentos externos como phpDocumentor puedan crear la documentación API en buen formato y fácil de entender.

• Permite que algunos IDEs como Zend Studio, NetBeans y Aptana Studio interpreten los tipos de variables y otras ambigüedades en el lenguaje de programación.

Todo esto a través de Docblocks, un Docblock no es más que un bloque para documentar un bloque de código. Comienza con / ** y tiene un asterisco al principio de cada línea. Ejemplo:

/**
 * Saluda al visitante
 * 
 * Une la palabra hola con el nombre del visitante
 * 
 * @param string $nombre nombre del visitante
 * @return string saludo completo
 */
function saludo($nombre) {
    return 'hola ' . $nombre;
}

Descargando apigen

Nos dirigimos a la página de apigen http://www.apigen.org/ y buscamos la parte de descargas, y descargamos el archivo .phar,  esta es la última versión http://apigen.org/apigen.phar

Movemos el archivo apigen.phar al directorio de instalación de php, en mi caso que estoy trabajando con WAMP es en  C:\wamp\bin\php\php5.5.12\

Generando la documentación de código php

Para generar la documentación lo haremos por línea de comandos, y crearemos un archivo .bat para ejecutar cada vez que queramos generar la documentación.

Crear un archivo llamado documentar_apigen.bat, este archivo puede estar en cualquier directorio del sistema, y debe contener las siguientes instrucciones:

C:\wamp\bin\php\php5.5.12\php.exe "C:\wamp\bin\php\php5.5.12\apigen.phar" generate --source "C:\wamp\www\dir" --destination "C:\wamp\www\docs\apigen" --title "Titulo de proyecto" --charset "UTF-8" --access-levels "public" --access-levels "protected" --access-levels "private" --tree

Explicación:

--source “carpeta de la ubicación de nuestro código php” 
--destination "carpeta donde guardar la documentación"
--title "Titulo de tu proyecto"
--charset "codificación de los archivos de código fuente, utilizar UTF-8 para tildes y caracteres  especiales"
--access-levels "niveles de acceso para las clases, sus métodos y atributos"
--tree genera un árbol con las clases de tu proyecto con jerarquías de  acuerdo a las herencias.

Ahora ejecutamos el archivo documnetar_apigen.bat, y taran funciona, ya hemos generado la documentación de nuestro código php, para volver a genera la documentación solo volveremos a ejecutar este archivo.