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:
/**
* 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
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:
| Marca | Significado |
| @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)
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
