Doxygen una herramienta para documentar código

Doxygen es un generador de documentación para C++, C, Java, Objective-C, Python, IDL (versiones Corba y Microsoft), VHDL y en cierta medida para PHP, C# y D. Dado que es fácilmente adaptable, funciona en la mayoría de sistemas Unix así como en Windows y Mac OS X. La mayor parte del código de Doxygen está escrita por Dimitri van Heesch.
Doxygen es un acrónimo de dox(document) gen(generator), generador de documentación para código fuente.

Comenzar a documentar

Doxygen es un programa que analiza el código en busca de directivas en forma de comentarios y las transforma en documentación, bien HTML, bien LaTeX e incluso podemos crear una página de manual de linux para visualizar con el mítico comando “man”. Doxygen acepta multitud de lenguajes como C/C++ o Java. La principal ventaja de Doxygen es sin duda que las directivas no son más que comentarios de forma que no tenemos que crear una documentación aparte, sino, simplemente, comentar el código.
Un ejemplo sencillo. Supongamos la siguiente cabecera de función:

/**
 * @brief Multiplica 2 matrices 3x3 y devuelve el resultado
 * @param A La primera matriz a multiplicar de tamaño 3x3
 * @param B La segunda matriz a multiplicar de tamaño 3x3
 * @return Una nueva matriz C = AxB.
 */
float ** multiplicaMatrices (float **A, float **B);

Sin tener ni idea de doxygen, ya se puede intuir lo que quieren decir los comentarios. Gracias a estos comentarios (y la documentación generada posteriormente a partir de estos) podemos saber que esta función multiplica matrices 3×3 sin tener que conocer la implementación.

El estilo que se utiliza es un estilo similar a Javadoc

¿Que hay que documentar?

¿de qué se encarga una clase? ¿un paquete?
¿qué hace un método?
¿cuál es el uso esperado de un método?
¿para qué se usa una variable?
¿cuál es el uso esperado de una variable?
¿qué algoritmo estamos usando? ¿de dónde lo hemos sacado?
¿qué limitaciones tiene el algoritmo? ¿… la implementación?
¿qué se debería mejorar … si hubiera tiempo?
¿Cuándo hay que poner un comentario?
Por obligación:

  1. al principio de cada clase
  2. al principio de cada método
  3.  ante cada variable de clase

Por conveniencia (una línea):

  1.  Al principio de fragmento de código no evidente
  2.  A lo largo de los bucles

Y por si acaso (una línea):

  1.  Siempre que hagamos algo raro
  2. Siempre que el código no sea evidente

Es decir, que los comentarios más vale que sobren que que falten.

IMPORTANTE: cuando un programa se modifica, los comentarios deben modificarse al tiempo, no sea que los comentarios acaben refiriéndose a un algoritmo que ya no utilizamos.

Algunas etiquetas que utilizaremos

las etiquetas mas comunes son:

brief: Indica que lo que sigue a continuación es el resumen de la función/clase/estrucura/enumerado/etc documentado.
param: Parámetro de una función. Debe estar seguido del nombre de la variable a la que nos referimos. Por ejemplo:

@param a explicacion de la variable
return: Lo que devuelve la función
note: Una anotacion.
see: Referencia a una función.
En el estilo JavaDoc la primera linea siempre se tomará como un brief. Cualquier linea que no comience con una etiqueta se supone que forma parte de la descripción extendida (siempre y cuando haya una linea en medio):

/**
 * @brief Descripción resumida
 * Aqui sigue siendo un resumen
 *
 * Esto ya es la descripción detallada
 */

No tenemos que definir los comentarios justo antes de la declaración, podemos ponerlos justo después mediante comentarios en linea que comienzan por ‘<‘. Si el comentario es una única linea indica una descripción resumida:

int a; ///&lt; Descripción resumida de a
char b; //!&lt; Descripción resumida de b
Los comentarios en bloque indican descripción extendida:
float c; /*!&lt; Descripción extendida de c*/
bool d; /**&lt; Descripción extendida de d*/

Tambien podemos documentar algo en otra parte del código indicando a qué hace referencia con las directivas:

  • struct para documentar una estructura
  • union para documentar una union
  • enum para documentar un enumerado
  • fn para documentar una función
  • var para documentar una variable, typedef o enum
  • def para documentar un #define
  • typedef para documentar un typedef
  • file para documentar un archivo
  • namespace para documentar un namespace
  • class para documentar una clase c++ o Java
  • package para documentar un paquete Java

interface para documentar una interfaz
Ejemplo:

/**
 * @class miClase
 * @brief Representa una clase vacía
 */
 
/**
 * @struct miEstructura
 * @brief Representa una estructura vacia
 */
 
// Antes o después de los comentarios o incluso en otro fichero...
 
class miClase{
  ...
};
 
struct miStruct{
  ...
};

Doxygen permite insertar código de otras herramientas, como por ejemplo “dot”, que permite crear diagramas especificando su aspecto mediante texto.
Generando la documentación:
Una vez comentado nuestro código procedemos a ejecutar Doxygen para que genere automáticamente nuestra documentación. A este programa lo único que tenemos que indicarle es un archivo de configuración, el cual podemos generar mediante el comando.

$ doxygen -g

Lo cual nos creará el archivo “Doxyfile”. Pasamos a modificarlo. No tendremos problemas a la hora de entender las opciones ya que hay multitud de comentarios. Por ejemplo, cambiaremos:

linea 28: El nombre del proyecto (Por ejemplo PROJECT_NAME = "Proyecto de prueba") 
linea 34: La versión (PROJECT_NUMBER = 0.1.2) 
linea 41: Directorio de salida (OUTPUT_DIRECTORY = ./doc) 
linea 63: El idioma (OUTPUT_LANGUAGE = Spanish) 
linea 584: Los ficheros de entrada (INPUT = ./include/cabecera.h ./src/main.cpp clase.java) 
linea 700: Si queremos poder navegar por el código (SOURCE_BROWSER = YES) 
linea 777: Si queremos generar la documentación HTML (GENERATE_HTML = YES por defecto) 
linea 1088: Si queremos generar la documentación LaTeX (GENERATE_LATEX = YES por defecto) 
linea 1216: Si queremos generar la documentación MAN (GENERATE_MAN = YES) 
linea 1245: Si queremos generar la documentación XML (GENERATE_XML = YES)

Podemos tardar un buen rato en configurar la documentación a nuestro gusto. Una vez que ya lo tenemos simplemente ejecutamos

$ doxygen

Lo que nos creará la documentación en el formato especificado. Si hemos indicado que genere documentación HTML (por defecto) generará, entre otros, un archivo index.html en la carpeta HTML que podremos abrir con un navegador. Como ya habíamos comentado, también es posible generar documentación en LaTeX y man entre muchos otros.

y así es como quedaría la web documentada:

Xcode_Doxygen

Be the first to comment on "Doxygen una herramienta para documentar código"

Deja un comentario.

Tu dirección de correo no será publicada.


*


*