¡Hola a todos! En artículos anteriores les comenté sobre cómo generar documentación a partir del código fuente utilizando Doxygen y JSDuck. En la entrada de hoy les comentaré sobre phpDocumentor, una de las herramientas más utilizadas para estos fines en PHP.

phpDocumentor-logo

Con phpDocumentor la documentación se distribuye en bloques. Estos bloques siempre se colocan justo antes del elemento al que documentan y su formato es:

/**
* Descripción breve (una línea)
*
* Descripción extensa. Todas las líneas que
* sean necesarias
* Todas las líneas comienzan con *
  <- Esta línea es ignorada
*
* Este DocBlock documenta la función suma()
*/
function suma()
{
  ...
}


Los elementos que pueden ser documentados son:

  • define.
  • function.
  • class.
  • class vars.
  • include/require/include_once/require_once.
  • global variables.

Además se puede incluir documentación globlal a nivel de fichero y clase mediante la marca @package
Dentro de un bloque DocBlock se pueden incluir marcas que serán interpretadas por phpDocumentor de forma especial.
Hay una serie de marcas estándar que pueden ir dentro de todos los DocBlock:

  • @access: Si @access es ‘private’ no se genera documentación para el elemento (a menos que se indique explícitamente). Muy interesante si sólo se desea generar documentación sobre la interfaz (métodos públicos) pero no sobre la implementación (métodos privados).
  • @author: Autor del código.
  • @copyright: Información sobre derechos.
  • @deprecated: Para indicar que el elemento no debería utilizarse, ya que en futuras versiones podría no estar disponible.
  • @example: Permite especificar la ruta hasta un fichero con código PHP. phpDocumentor se encarga de mostrar el código resaltado (syntax-highlighted).
  • @ignore: Evita que phpDocumentor documente un determinado elemento.
  • @internal/inline {@internal}}: Para incluir información que no debería aparecer en la documentación pública, pero sí puede estar disponible como documentación interna para desarrolladores.
  • @link/inline {@link}: Para incluir un enlace (http://…) a un determinado recurso.
  • @see: Se utiliza para crear enlaces internos (enlaces a la documentación de un elemento).
  • @since: Permite indicar que el elemento está disponible desde una determinada versión del paquete o distribución.
  • @version: Versión actual del elemento.

Ejemplo:

/**
* Emilious Sender (class worker) 🙂
*
* Envio de emails (MIME - multipart)
*
* Codificacion de mensajes segun RFC-822
* Utiliza la especificacion mime
* Permite enviar ficheros adjuntos utilizando
* Permite el envio a multiples destinatarios
*
* @author Enrique Fernandez-Perera [Epsilon Eridani]
* @author http://www.epsilon-eridani.com
*
* @package Emilious_Sender
*/
class Emilious_Sender
{
  //// aqui la implementacion de la clase
}

Y existen otras marcas que sólo se pueden incluir en los bloques de determinados elementos:

Declaración de funciones (elemento function)

  • @global: Permite especificar el uso de variables globales dentro de la función.
  • @param: Parámetros que recibe la función. Formato: * @param tipo $nombre_var comentario.
  • @return: Valor devuelto por la función. Formato: * @return tipo comentario.

Los tipos de datos en PHP (para indicar en @param, @return, etc…) son:

  • array
  • string
  • boolean
  • integer
  • float
  • object
  • mixed

Ejemplo:

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

Ejemplo de documentación de un método privado (la documentación no aparecerá a menos que se especifique de forma explícita):

/**
* localiza las imagenes dentro del contenido
*
* @access private
* @param string $dir_imagenes path al directorio de imagenes
*/
function encuentra_html_imagenes($dir_imagenes)
{
   ....
}

Ejemplo de un comentario interno, @internal, que no aparecerá en la documentación de interfaz (documentación pública).

/**
* cuerpo del mensaje
*
* Para mandar texto HTML, $body tiene que ser un array
* de la forma (es preferible utilizar body_html()):
* $body['html'] = $texto_html;
* $body['texto'] = $texto_plano; (opcional)
* $body['dir_imagenes'] = $dir_imagenes; (opcional)
*
* @internal Si $this->body_con_html==true el valor de $ctype no se tiene en cuenta.
*
* @param mixed $body contenido del mensaje
* @param string $ctype (opcional) mime-type del contenido (text/plain si es texto)
* @param string $charset (opcional)
*/
function body($body, $ctype="", $charset="")
{}

Variables de clase (atributos)

@var: Documenta los atributos de la clase. Formato: * @var tipo comentario.

Ejemplo:

/**
* array de destinatarios del mensaje
* @var array destinatarios
* @access private
*/
var $to;

Generar la documentación

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

Opciones para generar documentación:

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

¿Qué hay que especificar?

  1. El directorio en el que se encuentra nuestro código. phpDocumentor se encarga de recorrer los subdirectorios de forma automática.
  2. Opcionalmente los paquetes (@pakage) que deseamos documentar, lista de ficheros incluidos y/o excluidos y otras opciones interesantes para personalizar la documentación.
  3. El directorio en el que se generará la documentación.
  4. 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).
  5. El formato de salida de la documentación.

Formatos de salida

  1. HTML a través de un buen número de plantillas predefinidas (podemos definir nuestra propia plantilla de salida).
  2. PDF.
  3. 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

En este artículo sólo se han incluido algunas pinceladas sobre esta herramienta. Los que quieran probarla pueden descargarla aquí. Para saber más puedes echar un vistazo en www.phpdoc.org.

Fuente: Epsilon-eridani.com