Blog

Dori Lopez Nieves | 1 comentario

Para PHP una de las herramientas más utilizadas es phpDocumentor (www.phpdoc.org).

El funcionamiento básico se representa en el siguiente esquema:

Documentando el código PHP

Los elementos en php se documentarán mediante bloques de código comentado que se sitúan justo antes del elemento que documentan.

Tienen la siguiente forma:

/**
* Descripción breve (una línea)
*
* Descripción extensa. Todas las líneas que
* sean necesarias se pueden ir incluyendo.
* */
function suma() { ... }

Dentro de un bloque se pueden incluir marcas que serán interpretadas por phpDocumentor de forma especial. Se indican mediante una etiqueta precedida de una @. Ejemplo: @author.

Algunos de los elementos imprenscindibles a documentar son:

• @author –> inidicar el autor de un fragmento de código.
• @link –> introducir un enlace (http) en la documentación que se genera.
• @param –> Indicar los parámetros que recibe la función que estamos documentando.
• @return –> Indicar lo que devuelve la función que estamos documentando.

Ejemplo de documentación de una función:

/**
* Verifica si una direccion de correo es correcta o no.
*
* @author Dori
* @return boolean true si la direccion es correcta
* @param string $email direccion de correo
*/
function check_dir_email ($email)
{
....
}

Generando la documentación.

phpDocumentor permite generar la documentación de varias formas y en varios formatos.

Opciones para generar documentación:

• Desde línea de comandos (php CLI – Command Line Interpreter)
• Desde interfaz web (incluida en la distribución)
• Desde código. Como phpDocumentor está desarrollado en PHP, podemos incluir su funcionalidad dentro de scritps propios.

¿Qué hay que especificar?

• El directorio en el que se encuentra nuestro código. phpDocumentor se encarga de recorrer los subdirectorios de forma automática
• Opcionalmente los paquetes (@pakage) que deseamos documentar, lista de ficheros incluidos y/o excluidos y otras opciones interesantes para personalizar la documentación.
• El directorio en el que se generará la documentación
• Si la documentación va a ser pública (sólo interfaz) o interna (en este caso aparecerán los bloques private y los comentarios @internal).
• El formato de salida de la documentación

Formatos de salida

• HTML a través de un buen número de plantillas predefinidas (podemos definir nuestra propia plantilla de salida)
• PDF
• XML (DocBook). Muy interesante puesto que a partir de este dialecto podemos transformar (XSLT) a cualquier otro utilizando nuestras propias reglas y hojas de estilo.

Más información sobre phpDocumentor

Para saber más puedes echar un vistazo en www.phpdoc.org

Documentar código con phpdoc fue posteado el enero 23, 2012 a las 16:11 en CakePHP, PHP y. fue modificado el enero 23, 2012 at 16:21. Puedes seguir cualquier respuesta a esta entrada a través de la RSS 2.0 feed. Puedes dejar una respuesta o hacer un trackback desde tu web.

Compartir: Twitter, Facebook, Delicious, Digg, Reddit