Blog


23
enero
- 2012 -
Dori Lopez Nieves

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

|

1 Comentario

soledad on 01/25/2013 at 16:07.

hola:

me gustarias saber cuales son los pasos a seguir para documentar el codigo con el phpdocumentor.. es primera vez que ocupo herramienta
si me pudireras ayudar gracias…

Responder

Deja tu comentario

Tranquilo, tu email no será publicado o compartido.
Rellena los campos obligatorios marcados con *


*

Puedes utilizar etiquetas HTML con sus correspondientes atributos: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>