Generar documentación de aplicaciones PHP

Todo buen programador debe estar consciente de la importancia que tiene documentar sus aplicaciones, no sólo para que los demás puedan entender exactamente lo que hace y su funcionamiento, más que todo es para que otro programador pueda darle mantenimiento en cualquier momento, sobre todo cuando la aplicación se desarrolla en equipo.

Cabe destacar que antes de comenzar a generar la documentación debemos saber como escribirla, para esto pueden seguir los lineamientos haciendo clic aquí. Después de saber como poner nuestros comentarios estandarizados, procedemos a descargar el phpDocumentor mediante PEAR y estar seguros que nuestro php.ini relativo al CLI contempla la librería php-xsl. Las instalaciones a continuación son hechas desde un ambiente Debian, pero con el respectivo manejador de paquetes debería funcionar para cualquier distribución.

Instalación de pear:

apt-get install php-pear
pear channel-discover pear.phpdoc.org
pear install phpdoc/phpDocumentor-alpha

Con esto ya hemos instalado la aplicación PEAR que realmente nos sirve para instalar y manejar extensiones y complementos en PHP. Lo siguiente es verificar si en el entorno de configuración para consola está incluida la libreria XSL, para hacer eso basta con escribir lo siguiente:

php -i | grep xsl

Si no obtenemos resultado quiere decir que no la tenemos instalada. Para instalarla el procedimiento es sencillo, después de la instalación reiniciamos el servidor apache para que tenga efecto la inclusión:

apt-get install php5-xsl
/etc/init.d/apache2 restart

Ya todo está listo para empezar a generar la documentación de una forma automática y bien sencilla, supongamos que tenemos nuestra aplicación en /var/www/ usamos el comando como sigue:

phpdoc -d /var/www/ -t docs

Usamos -d y una ruta para indicarle que va a incluir para la documentación, es decir, donde se encuentra nuestra aplicación, la opción -t y la ruta la usamos para indicarle en que directorio va a ser generada la documentación. Si el directorio destino no existe, es creado de forma automática, si por el contrario ya existe los archivos son reemplazados.

Ahora bien, supongamos que estamos usando un librería de terceros como mPDF para generar documentos PDF, no queremos documentar dicha librería en nuestra aplicación, para eso usamos el parámetro –ignore, al cual se le pueden pasar múltiples rutas para excluir más de un directorio y sus subdirectorios. En el próximo ejemplo voy a excluir mPDF y PHPMailer, partiendo desde la premisa que dichas librerías están localizadas en el directorio libs de nuestra aplicación:

phpdoc -d /var/www/ -t docs --ignore="/var/www/libs/mPDF/* /var/www/libs/PHPMailer/*"

Después de unos segundos (o minutos, dependiendo del tamaño del proyecto) la documentación será generada y podemos ir al navegador web y con la ruta destino que específicamos entrar a los documentos, en mi caso fue generado local en http://127.0.0.1/docs.

Espero este breve manual les haya sido de mucha ayuda.