Manual de uso de

Documentacin automtica de C++ estndar mediante Doxygen

http://www.doxygen.org/

ndice
1Introduccin........................................................................................................................................3 2Instalacin...........................................................................................................................................3 3Obtener la documentacin de un proyecto.........................................................................................4 4Documentar un proyecto....................................................................................................................6

1 Introduccin
Doxygen es un documentador automtico, capaz de extraer la documentacin de los propios fuentes del programa. Es capaz de extraer documentacin especialmente de Java, C y C++, si bien otros lenguajes como Python tambin estn soportados. En este documento se describe de manera sencilla las operaciones ms comunes con esta herramienta: el formato de los comentarios en el cdigo fuente (el pequeo precio que hay que pagar para poder disfrutar de estas ventajas), la configuracin de Doxygen y su ejecucin para la obtencin de la documentacin. Doxygen se basa principalmente en JavaDoc, una herramienta que desde finales de los aos 90 se distribuye con el lenguaje de programacin Java, y que funciona exactamente de la misma forma (si bien Doxygen cubre muchos ms lenguajes y aporta mucha ms funcionalidad).

2 Instalacin

Figura 1: Doxywizard, la interfaz grfica de Doxygen Si bien Doxygen1 es una herramienta de lnea de comando, al que hay que pasarle un archivo de configuracin preparado para el proyecto previamente, el trabajo se alivia bastante empleando Doxywizard, una interfaz grfica para Doxygen que se instala automticamente con la versin para windows, pero que hay que instalar aparte (doxygen-gui) en entornos Linux. Su aspecto en todos los sistemas (incluyendo tambin Mac), es el que se muestra en la figura 1. Para su correcto funcionamiento, precisa del paquete de diagramacin GraphViz2, que en entornos Linux se instala de manera muy sencilla segn la distribucin usada, pero que en entornos Windows es necesario retocar para su correcta disponibilidad. Para que Doxygen encuentre a GraphViz, es necesario que ste ltimo se encuentre en las rutas del sistema, almacenadas en la variable PATH. As, una vez instalados ambos paquetes (supongamos en la unidad C:), ser necesario ejecutar las siguientes rdenes para trabajar correctamente. set PATH=c:\archivos de programa\graphviz\bin\;%PATH% doxywizard
1 http://www.doxygen.org 2 http://www.graphviz.org

En caso de que no se instale el paquete GraphViz, se pierden los grficos de llamadas a funciones, lo cul tampoco es vital si no se precisa.

3 Obtener la documentacin de un proyecto

La manera ms sencilla para trabajar con Doxygen es utilizar el Wizard (asistente). Durante esta seccin se asumir que se desea documentar un proyecto de gestin temperaturas que reside en un directorio llamado GestionTemperaturas. Si se pulsa en el botn Wizard (figura 2), aparece el asistente que nos permitir obtener la documentacin del proyecto. En primer lugar, se pregunta el ttulo de la documentacin, en project name. Lo ms importante aqu, en cualquier caso, es indicar el lugar donde residen los fuentes (source code directory), as como el lugar donde se va a generar la documentacin (desination directory). Una buena idea es crear un subdirectorio dentro del directorio del proyecto (como doc, en el ejemplo), de manera que siga estando todo localizado en un mismo lugar.

Figura 2: Utilizando el asistente para configurar Doxygen A continuacin, se selecciona el lenguaje de programacin a emplear para el proyecto (figura 3). En realidad, Doxygen genera la documentacin en cualquiera de las formas, pero seleccionando el lenguaje de programacin la salida est mucho ms pulida. En este caso, se ha elegido C, puesto que aunque se emplee en realidad C++, no estamos utilizando programacin orientada a objetos, que es lo que ms le afectara al documentador.

Figura 3: Seleccin entre lenguajes de programacin disponibles.

Las dos primeras opciones son mucho ms interesantes: Documented entities only / All entities. La primera se refiere a incluir en la documentacin slo aquellas entidades (funciones, constantes, ...), para la que se ha escrito informacin especdifca. La segunda documenta todo en el programa. Probablemente la primera sea interesante para usuarios de una librera o aplicacin, mientras la segunda es ms interesante para los desarrolladores de la misma. Finalmente, include cross-reference source code in the output, incluye el cdigo fuente, de manera que se pueda navegar por l, desde la propia documentacin, de funcin en funcin. El tipo de documentacin a generar es lo siguiente a elegir, tal y como se ve en la figura 4. Probablemente, la salida ms til sea HTML, aunque el formato RTF puede ser mucho ms interesante para cuando se desea obtener un manual impreso. Para terminar, los diagramas a generar, como se aprecia en la figura 5.

Figura 4: Ttulo del proyecto. Sin duda, lo mejor es utilizar dot tool de GraphViz, puesto que el diagramador interno de Doxygen no es demasiado completo (no genera los grafos de llamadas entre funciones, por ejemplo). Por defecto aparece desmarcada la opcin call graphs, que precisamente son los grafos que se acaban de mencionar.

Figura 5: Perfiles y seleccin del compilador. Slo queda un pequeo detalle: Doxygen genera toda la documentacin en ingls, por lo que si se desea cambiarlo a espaol, se debe acceder a la configuracin avanzada: se puede hacer fcilmente, pulsando en expert (figura 6). En output language, el men desplegable permite elegir espaol (Spanish) como lengua de salida.

Figura 6: Configuracin experta de doxygen, necesaria para cambiar la lengua de salida. Una vez hecho todo sto, slo es necesario guardar el archivo configurador para Doxygen (pulsando save) en alguna parte. El mejor lugar es el directorio doc creado dentro del directorio del proyecto. Tambin se debe elegir el directorio de trabajo (working directory), que de nuevo debera ser este directorio doc. Una vez pulsado Start, la documentacin habr sido creada dentro del ya mencionado directorio doc, tpicamente ser doc/html. Slo es necesario ya ejecutar el navegador sobre el archivo index.html para poder navegar por toda la documentacin generada.

4 Documentar un proyecto
Aunque Doxygen realiza muchas tareas por el programador, obviamente no puede saber lo que significa una constante, o para qu sirve una funcin. Precisamente esa informacin debemos hacrsela saber mediante unos comentarios especiales. Un comentario de varias lneas en C++ empieza por /*. Si el comentario empezara por /**, Doxygen tomar este comentario como que contiene informacin importante para l, y lo procesar. En cuanto a los comentarios de una sola lnea: //, es necesario aadirles una barra ms: ///. Dentro de uno de estos comentarios especiales, puede incluirse varia informacin, para lo cul se utilizan las siguiente etiquetas (que son las ms tiles y empleadas, aunque existen muchas ms): Etiqueta Significado
@param @return @brief

Informacin sobre un parmetro de una funcin. Informacin sobre lo que devuelve una funcin. Explicacin muy breve sobre lo que hace una funcin, de manera que no sea necesario verse toda la documentacin en detalle. Aparece en el ndice general. Aviso que aparece resaltado en la documentacin de una

@note

Etiqueta funcin.
@see

Significado

Permite establecer referencias cruzadas con otras entidades. Estos comentarios con informacin extra deben incluirse en los archivos de cabecera o .h, ya que son legibles para el ser humano, y ese es precisamente el lugar donde pueden ser de utilidad para aquellos que empleen las libreras generadas por otros programadores. Un par de ejemplos son los siguientes:
// gestionvectores.h /** @brief Modifica un valor ya existente Modifica un valor ya existente, en la posicin y con el valor indicado. @note la posicin debe ser menor que el nmero de elementos @param v El vector de reales @param numEltos El nmero de elementos a valorar en el vector @param pos La posicin a modificar @param valor El nuevo valor a escribir en la posicin pos

*/ bool modificaEnVector(double v[], int numEltos, int pos, double valor); // estadistica.h /** La funcin calcula la media del vector pasado por parmetro @param v El vector de reales @param numEltos El nmero de elementos a valorar en el vector @return La media como nmero real

*/ double calculaMedia(double v[], int numEltos);

/// @return La desviacin tpica de los elementos del vector /// @see calculaMedia double calculaDesvTipica(double v[], int numEltos);

Doxygen tiene muchas ms posibilidades y ventajas, pero su manejo bsico no supone conocer ms que estos detalles. El precio a pagar para que Doxygen genere una buena documentacin, es, smplemente, utilizar un formato especial para los comentarios que se incluiran para describir las funciones, el cul es un precio realmente barato.

Una muestra del resultado puede verse a continuacin.