Documentando el Código de PHP con Netbeans

Como siempre es Buena práctica documentar nuestro trabajo, en el desarrollo, el código fuente no es la excepción. Sin embargo, si no se cuenta con las herramientas necesarias, puede ser un trabajo tedioso. Una gran idea (¿introducida en Javadocs™?) fue la de documentar el código fuente al tiempo que se escribía dicho código. Esto ahorraba mucho tiempo a la vez que permitía al mismo programador realizar la documentación. El lenguaje que introdujo esta idea fue Java, con la herramienta Javadocs, utilizando una especie de anotaciones – una palabra seguida del carácter arroba – para realizar esta documentación.

En PHP también existen herramientas similares para generación de código. La que veremos a continuación es una de las más populares: ApiGen, que soporta la mayoría de anotaciones para documentar código fuente. Para más información acerca de las anotaciones soportadas, revise este enlace.

Cómo se escribe la documentación en el código.

Es fácil, sólo hay que escribir dentro comentario múltiple (que inicie con los caracteres /**) y luego, dentro de este utilizar las anotaciones, como se ve en el ejemplo siguiente:

/**

* Almacena la información de una persona.

* @author Wilman Vega <wilmanvega@gmail.com>

* @see Usuario

*/

En entornos de desarrollo, como Netbeans se utilizan más fácil y rápido, debido a que se adapta al sistema de autocompletado de código de Netbeans, lo que permite escribir más rápido.

Paso 1. Descargar Apigen

Se debe ingresar a la página de Apigen (http://apigen.org) y descargar la última versión (Hay varias formas de instalar ApiGen, aquí instalaremos de forma independiente).

Una vez descargado Apigen, se descomprime el archivo en cualquier directorio de nuestro equipo. Preferiblemente, se puede descomprimir en el área donde se encuentra la instalación de PHP o el servidor de aplicaciones web.

Paso 2. Configurar Netbeans

Luego de que se descomprimen los archivos de Apigen, se debe configurar Netbeans para poder generar la documentación. Para esto, hacemos clic en Herramientas (Tools) > Opciones (Options) clic en el ícono de PHP y finalmente en la pestaña Apigen. Se hace clic en Examinar para buscar el script de Apigen (En Windows Apigen.bat). Finalmente, damos clic en el botón Ok para cerrar el cuadro de dialogo.

Paso 3. Escriba el código

Netbeans le ayuda a autocompletar inmediatamente usted digita el carácter arroba dentro de los comentarios especiales (/** y */)

Paso 4. Generar documentación

Ahora vamos a generar documentación de la aplicación. Hacemos clic derecho en el proyecto > clic en propiedades y luego la opción Apigen. Aquí, seleccionamos la carpeta donde va a ir la documentación (debe ser una carpeta dentro de la aplicación) y finalmente damos clic en Ok.

Finalmente, damos clic derecho en el proyecto > Generar documentación. Se puede apreciar la salida de Netbeans ejecutando el Script de Apigen. Al finalizar la ejecución del Script, se nos presenta un resumen y se abre el navegador con la documentación del proyecto.