phpDocumentor
Existen algunas herramientas que permiten generar documentación de forma automática a partir del código fuente. Javadoc es la herramienta estándar en Java. Para PHP una de las herramientas más utilizadas es phpDocumentor
De todos es sabido que es fundamental producir un código correctamente documentado.
¿Qué conviene documentar dentro del código?. Fundamentalmente tres cosas:
Tipo de documentación | Información | A quién va dirigida |
La interfaz | Qué hace (no como lo hace) una función
o un método de una clase. Qué parámetros hay que pasar. Qué devuelve. Ejemplo de uso. |
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. |
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 (p.e. por razones de rendimiento o por optimización
de recursos, etc..). |
Esta información interesa tanto a nivel
de implementación (desarrollador) como a nivel funcional (responsable
de desarrollo). |
Normalmente la información sobre la implementación no necesita salir del código.
Por el contrario, la información de la interfaz 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.
Existen algunas herramientas que permiten generar documentación de forma automática a partir del código fuente. Javadoc es la herramienta estándar en Java. Para PHP una de las herramientas más utilizadas es phpDocumentor (www.phpdoc.org).
El funcionamiento básico se representa en el siguiente esquema:
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: |
@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:
- 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)
- 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