Versión corta

Usando  /* */

/**

* @file_name     - archivo.php
* 
* @function_name - nombre de la función
*

* @short_description - descripción breve de la función o del archivo
* @full_description  - descripción de la función o del archivo
*
* @param1 string descripción

* @param2 int    descripción
*
* @return valor que regresa [string, array, int]
*
* @version 1
* @date begin 10/Abr/2008
* @date update 1/Feb/2009
*
* @author [ richard_site@dominio.com | www.richardsite.com.mx ]
*/

Usando //

// -----------------------------------------------------------
// descripción de la función o del archivo
// -----------------------------------------------------------
// @file archivo.php
// @param string
// @return valor que regresa [string, array, int]
// @version 1
// @author richard_site@email.com
// -----------------------------------------------------------




¿Qué documentar?

• La breve descripción.
• La implementación.
• La toma de decisiones.

La breve descripción

• Qué hace una función (no como lo hace).
• Qué hace un método de una clase.
• Qué parámetros hay que pasar.
• Qué devuelve.
• Ejemplo de uso.

A quién va dirigida: Esta información es útil para las personas que utilizan funciones o clases diseñadas por otros.

La implementación

• Dentro de una función, cómo se lleva a cabo cada paso.
• Por qué se utiliza esta variable y no aquella.
• Qué algoritmo se utiliza.
• Qué hacen los métodos privados de una clase.

A quién va dirigida: Esta información sólo interesa a las personas que necesiten depurar o actualizar el bloque de código.

La toma de decisiones

• Por qué se ha implementado de una determinada forma y no de otra
  • por razones de rendimiento
  • por optimización de recursos

Normalmente la información sobre la implementación no necesita salir del código.
A quién va dirigida: Esta información interesa tanto a nivel de implementación (desarrollador) como a nivel funcional (responsable de desarrollo).

Por el contrario, la información de la breve descripción conviene pasarla a un documento independiente del código fuente (manual de uso). La persona que necesite utilizar una determinada librería de clases o funciones tendrá toda la información necesaria: qué hace cada elemento y cómo se utiliza. No necesita acceder al código fuente.

El problema con este tipo de documentación es que cada vez que se modifica algo en el código (actualizaciones, corrección de errores, etc…) hay que reflejarlo también en el manual de uso… doble trabajo.

Lo ideal por tanto sería poder automatizar de alguna forma este proceso.

Herramientas para documentar

Existen algunas herramientas que permiten generar documentación de forma automática a partir del código fuente.

Java

Javadoc es la herramienta estándar en Java.

PHP

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

DocBlock

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

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

Marcas (tags)

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:

Ejemplo:

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

Declaración de funciones (elemento function)
Marca Significado
@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

NOTA: Tipos de datos en PHP (para indicar en @param, @return, etc…):

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)
Marca Significado
@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. Para saber más puedes echar un vistazo en www.phpdoc.org