Documentación proyecto con Doxygen

Como Infant finalmente se publicará en forma de librería hay que documentar de la mejor forma posible cada una de las clases disponibles para que sea posible su uso por terceras personas. Para ello a partir de un código bien comentado y por medio de Doxygen podemos generar de forma casi automática esa documentación permitiendo publicarla en formatos como HTML, LATEX, XML, PDF o RTF. Una vez descargada e instalada la herramienta los pasos a seguir son:

0. Comentar el código usando una de las siguientes posibilidades (que podéis emplear según vuestro gusto, la forma de darle visibilidad al comentario, etc. además en el manual oficial hay aun más formas como comentarios ) para marcar que se trata de un comentario que queremos procesar con Doxygen:

/**

* ... text ...

*/

/*!

* ... text ...

*/

///

/// ... text ...

///

//!

//!... text ...

//!

/********************************************//**

* ... comentario visible…

***********************************************/

/////////////////////////////////////////////////

/// ... comentario visible…

/////////////////////////////////////////////////

int variable; /**< comentario tras definición en una linea */

Por otro lado para definir del tipo de dato que se trata podemos emplear los siguientes comandos dentro de los comentarios precedidos o bien por „\” o por „@”.

· \class para documentar una clase.

· \struct para documentar un struct.

· \union para documentar una unión.

· \enum para documentar un tipo enumerado

· \fn para documentar funciones.

· \var para documentar una variable, un typedef o un valor enum.

· \def para documentar un #define.

· \typedef para documentar una definición de tipo.

· \file para documentar un fichero.

· \namespace para documentar un namespace.

· \package para documentar paquetes en Java.

· \interface para documentar interfaces.

Además y para definir otros datos que puedan ayudar a mejorar la documentación.

· \author para determinar el autor o autores (\autors) del código.

· \date para documentar la fecha del código o última modificación.

· \deprecated para indicar que el código está obsoleto.

· \example para mostrar ejemplos de código del uso de una clase.

· \include incluye datos de un determinado fichero.

· \param [dir] indica que se está describiendo el parametro nom_parametro y su dirección, que puede ser in, out o in,out.

· \return describe el valor devuelto por una función por ejemplo.

· \todo para marcar tareas pendientes.

· \version para indicar

1. Crear el fichero de configuración para el proyecto que queremos documentar. Podemos crear uno automático y completar los campos más importantes como nombre del proyecto, ruta, logo, ruta de salida, etc. en el fichero generado con el que no deberíais tener problemas ya que la plantilla generada está muy bien documentada. Para generar este documento tan solo debemos escribir el comando:

doxygen -g nombre_fichero

Los campos más importantes a completar en este fichero son:

PROJECT_NAME = nombre del proyecto

PROJECT_NUMBER = versión

PROJECT_BRIEF = resumen o descripción

PROJECT_LOGO = bueno este no es importante pero personaliza mucho la documentación y es la ruta de una imagen con dimensiones máximas de 50 x 200px con el logo del proyecto.

OUTPUT_DIRECTORY = directorio en el que se genera la documentación

INPUT = directorio en el que se encuentra el código a documentar

FILE_PATTERNS = si queremos que solo se documente ficheros de un tipo, p.e. *.cpp, *.h, etc.

2. Una vez generado y completado este fichero lo único que hay que hacer es ejecutar el comando siguiente lo que automáticamente generará (si no hemos modificado esta configuración en el fichero) documentación en HTML y LATEX.

doxygen nombre_fichero

Para que veáis como va quedando en el caso de la documentación de Infant os dejo una captura de una de las clases del proyecto creado solo a partir de la modificación de los parámetros del punto 1 del fichero de configuración ya que después podemos personalizar desde la cabecera HTML hasta los colores de la documentación.