View this PageEdit this PageUploads to this PageVersions of this PageHomeRecent ChangesSearchHelp Guide

doxygen cheat sheet

El programa de documentación de código el más extendido es el Doxygen (http://www.stack.nl/~dimitri/doxygen/).

El Doxygen es similar en espíritu al JavaDoc (el estándar en Java), en tanto que los programas se documentan dentro del propio código, de manera que cuando cambias el código es sencillo cambiar también la documentación. Una vez documentado el programa, se pasa el doxygen a los fuentes como si un compilador se tratara, pero en vez de usando un makefile, usando un fichero de configuración para doxygen. Como resultado de la "compilación" con doxygen, obtienes los documentos en varios formatos (HTML, RTF compatible con Word, PDF, etc).

El doxygen está instalado actualmente en chibiko (antes en seraphim). Para solaris, está empaquetado a partir de solaris 8. Pero como no es necesario generar la documentación desde la misma máquina que ha generado los ejecutables, no pasa nada si se compila el unite en solaris 7 (marina) y se genera la documentación en seraphim.

Al nivel más básico es poner dentro del código bloques del estilo de:

/**
 * Takes an integer and squares it
 * \param a The integer to be squared
 * \return The integer squared
 */
int square(int a);


Y cerca del comienzo de cada fichero un bloque que diga algo así como:

/**
 * \file filename.h
 * \brief one-liner summary of the file purpose
 * \author the usual copyright statement
 */


NOTA: Los bloques también se pueden empezar con un "/*!" en vez de "/**"; es equivalente ("/**" es lo que usaba el JavaDoc, el "/*!" es lo que usaba el sistema de documentación de Qt; doxygen soporta los dos).

Los bloques se ponen justo antes de la línea con la cosa a documentar (así, si quieres documentar una estructura, pones un bloque antes de la estructura y otro antes de cada miembro de la estuctura explicando qué es). Para comentarios cortos, se pueden poner en la misma línea de la siguiente manera:

/*! Another enum, with inline docs */
enum AnotherEnum 
{ 
  V1, /*!< value 1 */
  V2  /*!< value 2 */
};


Con eso hay para ir empezando (salvando la "compleja" tarea que generar un fichero de configuración para el doxygen; para eso dejo un manualillo a continucación de éste). Si se quiere profundizar un poco más de cómo va, aquí hay unos cuantos punteros:

Manual de Doxygen (cómo generar el fichero de configuración)

(extraído de http://www.vjuegos.org/Tutoriales/ManualDoxygen/ManualDoxygen.pdf, por Roberto Albornoz rcaf2003@hotmail.com ).

Manual de Doxygen

Doxygen es una herramienta para documentar código en java, C y C++. Pueden bajarlo desde http://www.doxygen.org

Una vez instalado el doxygen, supongamos que en el directorio por defecto c:\archivos de programa\doxygen, necesitamos agregarlo a la variable de entorno PATH para poder llamarlo desde cualquier directorio, así que abramos el archivo c:\autoexec.bat y agregamos la siguiente línea:
set path=c:\archiv~1\doxygen;%path%

Ahora es necesario reiniciar el sistema para que se cargue la línea anterior, o pueden ejecutar el archivo autoexec.bat manualmente.

Ahora entramos al DOS y vamos al directorio de nuestro proyecto que queremos documentar, y creamos un directorio llamado doc, que contendrá toda la documentación.

Desde ahí ejecutamos el comando:

 doxygen ­g proyecto.cfg

Con esto creamos un archivo de configuración con el nombre "proyecto.cfg".

Ahora editaremos el archivo proyecto.cfg, por ejemplo con el edit:

 edit proyecto.cfg

Veamos ahora las líneas más importantes que tendremos que modificar:

  1. Aquí colocamos el nombre del proyecto.
    PROJECT_NAME = Nombre proyecto
  2. La versión de tu proyecto.
    PROJECT_NUMER = 1.0
  3. El archivo de salida para la documentación. Puede ser una ruta absoluta también.
    OUTPUT_DIRECTORY = doc
  4. El lenguaje para generar la documentación. En este caso será en español.
    OUTPUT_LANGUAGE = Spanish
  5. Esto es para que se extraiga todo, es decir documentará todos los archivos, incluyendo los que no tienen comentarios.
    EXTRACT_ALL = YES
  6. Directorio donde se encuentra el código fuente.
    INPUT = c:\proyectos\juego
  7. Esto indica que se procesarán todos los archivos .h y .cpp del directorio de tu proyecto
    FILE_PATTERNS = *.h *.cpp
  8. Para que lea todos los archivos que se encuentran en los subdirectorios de tu proyecto.
    RECURSIVE = YES

Y eso es todo, ahora ejecuten el siguiente comando:

 doxygen proyecto.cfg

Con esto comenzará el proceso de creación de la documentación.

Existe además otra utilidad llamada DOT para generar un diagrama de jerarquías de las clases que existen. Lo pueden bajar desde http://www.research.att.com/sw/tools/graphviz

Una vez instalado supongamos que en el directorio por defecto c:\archivos de programa\att\graphviz, modificaremos nuevamente el archivo proyecto.cfg creado anteriormente.

  1. Esto significa que utilizaremos la utilidad DOT.
    HAVE_DOT = YES
  2. La ruta donde se encuentra la utilidad DOT.
    DOT_PATH = c:\archiv~1\att\graphviz\bin

Para terminar veremos cual es el formato que debemos usar a la hora de documentar nuestro código fuente. Supongamos que tenemos una función que suma dos números, la documentación usando el estilo JavaDoc es la siguiente:
/*!
 \brief Suma dos números
 \param a: primer número
 \param b: segundo número
 \return La suma de a y b
 \see Resta, Multiplicación
 */
 int suma(int a, int b)
 {
    return a+b;
 }


Los comentarios en una sola línea se hacen así:

/*! Comentario en una sola línea */

Esto es lo más básico del uso del doxygen. A continuación les dejaré las direcciones para que puedan bajar directamente el doxygen y el dot.

ftp://ftp.stack.nl/pub/users/dimitri/doxygen-1.3.5-setup.exe
http://www.graphviz.org/pub/graphviz/ARCHIVE/graphviz-1.10.exe

Attachs

Doxyfile Ejemplo de fichero de configuración para doxygen (el usado para el API de Symbian en symbiandevel). Se ejecuta con "doxygen Doxyfile".