MASTER UNIVERSITARIO

SISTEMAS EMPOTRADOS

MEJORA Y MANTENIMIENTO
DE SISTEMAS EMBEBIDOS
1º CURSO

Trabajar con Doxygen

Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

INDICE
1 INTRODUCCIÓN ..............................................................................................................4
2 INSTALACIÓN Y CONFIGURACIÓN ....................................................................................5
3 CREAR FICHERO CONFIGURACIÓN DOXYGEN ...................................................................8
4 ANALIZAR DOCUMENTACIÓN GENERADA ...................................................................... 12
5 BUENAS PRÁCTICAS DOCUMENTACIÓN ......................................................................... 17
6 PREGUNTAS FRECUENTES ............................................................................................. 22

2 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

INDICE FIGURAS
Figura 1: Habilitar parámetro HAVE_DOT ........................................................................ 6
Figura 2: Habilitar parámetros CALL_GRAPH y CALLER_GRAPH ...................................... 6
Figura 3: Definir ubicación DOT_PATH ............................................................................. 7
Figura 4: Configuración apartado Project del Wizard ...................................................... 8
Figura 5: Configuración apartado Mode del Wizard ........................................................ 9
Figura 6: Configuración apartado Output del Wizard ...................................................... 9
Figura 7: Configuración apartado Diagram del Wizard .................................................. 10
Figura 8: Configuración IMAGE_PATH............................................................................ 10
Figura 9: Ejecutar la generación de la documentación .................................................. 11
Figura 10: Output del proceso de generación documentación...................................... 11
Figura 11: Página principal documentación HTML ......................................................... 12
Figura 12: Apartado Related Pages de la documentación ............................................. 12
Figura 13: Detalle de la sub sección Todo List de la documentación ............................. 13
Figura 14: Código fuente del fichero Sarrera.c con comentario @todo ........................ 13
Figura 15: Apartado Data Structures de la documentación ........................................... 14
Figura 16: Apartado Files de la documentación ............................................................. 14
Figura 17: Detalle del gráfico generado con dot ............................................................ 15
Figura 18: Detalle de la imagen incorporada a la documentación................................. 15
Figura 19: Código fuente del fichero main.c con comentario @image.......................... 16

3 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

1 INTRODUCCIÓN

En este documento se describirá cómo instalar las herramientas necesarias para poder
trabajar de forma básica en la generación de documentación con Doxygen.
En un primer apartado se describe la instalación y configuración de las herramientas
necesarias para poner en marcha Doxygen.
En un segundo apartado se detalla cómo definir un fichero de configuración que recoja
las opciones que parametrizarán la generación de documentación.
En un tercer apartado se presentan los ejemplos para el análisis de la documentación
generada basada en un software de ejemplo desarrollado por alumnos de 1º de Grado de
Informática y Grado Telecomunicaciones en ANSI – C.
Se describe en un apartado las buenas prácticas a la hora de incluir comentarios a la
documentación.
Se dedica un apartado a resolver las principales cuestiones planteadas al comenzar a
trabajar con Doxygen en un entorno de programación en ANSI-C.

4 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

2 INSTALACIÓN Y CONFIGURACIÓN

Esta guía describe los pasos a relizar para instalar y configurar Doxygen 1.8.6 y
GraphViz 2.36 en un equipo con Windows 7 64bit. Para otras versiones o para otros sistemas
operativos deberán consultarse los requerimientos de cada una de las aplicaciones instaladas
y/o buscar alternativas apropiadas para el sistema operativo.
1. Descarga doxygen
De la web www.doxygen.org en el apartado de download descargar el archivo auto
instaldor doxygen-1.8.6-setup.exe desde la siguiendo el enlace
http://www.stack.nl/~dimitri/doxygen/download.html#srcbin
Opcionalmente se pueden descargar también manuales y extensiones (Helper tolos
and scripts).
2. Instalación
Realizar la instalación utilizando el instalador (doxygen-1.8.6-setup.exe) en modo
administrador.
En el asistente seleccionar las opciones por defecto.
3. Instalación de GraphViz
Doxygen utiliza esta herramienta para renderizar imágenes de los diagramas
generados. Descargar el instalador (graphviz-2.36.msi) de GraphViz desde su sitio web
http://www.graphviz.org/Download.php.
A continuación realizar la instalación de GraphVis siguiendo las instrucciones y
opciones por defecto del instalador.
4. Configurar Graphviz en doxygen
Iniciar la aplicación Doxygen para realizar las configuraciones pertinentes.
Para habilitar en Doxygen la generación de diagramas basados en la librería DOT
proporcionada por la herramienta Graphviz (para más información sobre el lenguaje
DOT consultar http://www.graphviz.org/content/dot-language) se debe habilitar la
propiedad HAVE_DOT = YES disponible en la sección Expert > Dot.

5 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

Figura 1: Habilitar parámetro HAVE_DOT

En la sección Expert > Dot se activarán las opciones CALL_GRAPH y CALLER_GRAPH

Figura 2: Habilitar parámetros CALL_GRAPH y CALLER_GRAPH

6 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

A continuación se debe especificar la ruta donde se ubica el binario dot.exe

instalado con Graphviz. DOT_PATH = C:\Program Files (x86)\Graphviz2.36\bin

Figura 3: Definir ubicación DOT_PATH

7 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

3 CREAR FICHERO CONFIGURACIÓN DOXYGEN

Este apartado describe cómo configurar un fichero de doxygen para que realice la
generación automática de documentación de un proyecto desarrollado en ANSI-C.
1. Configuración básica
La configuración básica de un fichero de configuración Doxygen requiere completar los
siguientes apartados del wizard.
En la sección Project:
Project Name
Project synopsis (opcional)
Source code directory (scan recursively activado)
Destination directory

Figura 4: Configuración apartado Project del Wizard

En la sección Mode:
Select the desired extraction mode: All Entities (include cross-referenced source code
in the output)
Select programming language to optimize the results for: Optimize for C or PHP
output.

8 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

Figura 5: Configuración apartado Mode del Wizard

En la sección Output:
HTML > plain HTML (with search function)

Figura 6: Configuración apartado Output del Wizard

En la sección Diagrams:
Diagrams to generate:
Use dot tool from the GraphViz package

9 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

Figura 7: Configuración apartado Diagram del Wizard

2. Añadir imágenes del usuario

Complementariamente a los gráficos generados por Graphviz, si el usuario ha
generado imágenes (diagramas, figuras, etc.), éstas pueden publicarse en la
documentación ajustando la configuración como se describe a continuación.
En la sección Expert > Input, añadir la dirección donde se ubican las figuras que se
desean publicar. Para este ejemplo se añadirá el directorio docsrc donde se ubican 2
figuras. E:\MYMSE\doxygen\SARZAZU_dev\Proyecto\docsrc

Figura 8: Configuración IMAGE_PATH

10 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

3. Guardar la configuración
Guardar (File > Save as) la configuración para recuperarla en el futuro.

Figura 9: Ejecutar la generación de la documentación

4. Ejecutar la configuración
Desde la pestaña RUN iniciaremos la generación automática de la documentación. La
generación de la documentación HTML es ligera, pero la generación de los diagramas
requiere de más tiempo.

Figura 10: Output del proceso de generación documentación

11 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

4 ANALIZAR DOCUMENTACIÓN GENERADA

Este apartado describe los principales apartados de la documentación generada con

Doxygen.
1. Página principal de la documentación
En la ruta E:\MYMSE\doxygen\SARZAZU_doc\html se ubica el fichero index.html que
presenta la página principal de la documentación generada. Dispone de 4 secciones
principales y de un apartado para la búsqueda.

Figura 11: Página principal documentación HTML

2. Related Pages
En la sección “Related Pages” se presenta la subsección Todo List que recoge las tareas
pendientes del código, identificadas en el código con el parámetro @todo.

Figura 12: Apartado Related Pages de la documentación

12 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

Figura 13: Detalle de la sub sección Todo List de la documentación

Observar el fichero Sarrera.c con el código fuente y los comentarios. El comentario

precedido por el parámetro @todo genera la entrada en la lista de tareas pendientes.

Figura 14: Código fuente del fichero Sarrera.c con comentario @todo

3. Data Structures
En la sección “Data Sturctures” se presenta las estructuras de datos.

13 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

Figura 15: Apartado Data Structures de la documentación

4. Files
En la sección “Files” se presentan todos los ficheros de código documentados por
Doxygen.

Figura 16: Apartado Files de la documentación

Accediendo al fichero principal main.c se puede iniciar el análisis de la aplicación desde

la documentación apoyándose en los gráficos navegables generados.

14 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

Figura 17: Detalle del gráfico generado con dot

Observar que en la página de documentación de main.c se ha incorporado la imagen

que describe el flujo general del proyecto. Esta imagen se había generado
externamente e incorporado al directorio
E:\MYMSE\doxygen\SARZAZU_dev\Proyecto\docsrc

Figura 18: Detalle de la imagen incorporada a la documentación

15 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

A continuación se muestra un fragmente de los comentarios añadidos al fichero main.c

previos a la generación de la documentación con Doxygen.

Figura 19: Código fuente del fichero main.c con comentario @image

16 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

5 BUENAS PRÁCTICAS DOCUMENTACIÓN

A continuación se enumeran algunas de las buenas prácticas en la documentación de

código ANSI-C con Doxygen.

 Seleccionar un estilo de comentario (entre las diferentes opciones)

Doxygen nos proporciona diferentes posibilidades para añadir comentarios al código.
Analizar la sección correspondiente a Comment blocks for C-like languages
En esta documentación seguiremos la siguiente sintaxis para bloques de comentarios:

/**
* ... text ...
*/
El comentario comienza con los caracteres /** y finaliza con los caracteres */
Aunque en las líneas intermedias podría omitirse el carácter * se recomienda
mantenerlo para identificar claramente que se trata de una línea de comentario.
 Realizar bloques de comentarios que se identifiquen con facilidad
Si deseamos crear bloques de comentarios que tengan mayor visibilidad en la
documentación, se puede utilizar la siguiente sintaxis:

/********************************************//**
* ... text
***********************************************/
Obsérvese, que al final de la primera línea de comentarios se incluyen 2 caracteres //.
De esta forma finalizamos un comentario e iniciamos otro.
 Respetar la indentación
Respetar la indentación mejora la estructuración y legibilidad de los comentarios.
Evitar casos como el expuesto a continuación

/**
* ... text
*/
 Parámetros @brief y @file
En la cabecera del fichero describe la descripción general del fichero.

/********************************************//**
* @file fichero.c
* @brief Descripcion del fichero
************************************************/
Es obligatorio identificar el fichero para mostrar su descripción @brief en la
descripción general de la sección Files del menú de Doxygen. En fundamental respetar
el nombre del fichero.

17 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

Si activamos el modo JAVADOC_AUTOBRIEF = YES podemos omitir el parámetro

@brief y conseguir el mismo resultado.

/********************************************//**
* @file fichero.c
* Descripcion del fichero
************************************************/
 Parámetro @param
Nos permite identificar los parámetros de funciones (@param). Opcionalmente
podemos definir el sentido/orientación de los parámetros [in][out].

/********************************************//**
* @file copia.c
* @brief Copia bytes de un area de memoria origen
* a un area de memoria destino
* @param[out] dest Area de memoria destino
* @param[in] src Area de memoria origen
* @param[in] n Numero de bytes a copiar
************************************************/
 Parámetro @return
Describe los valores devueltos de una función.

/********************************************//**
* @file fichero.c
* @brief Descripcion del fichero
* @return Array con coordenadas
************************************************/
 Parámetro @todo
Indica una sección de comentarios para una tarea pendiente de realizar. Esta
descripción se añadirá a la sección TODO de tareas pendientes (en la sección Related
pages del menú, en la sub sección Todo List). Cada parámetro @todo genera una tarea
independiente.

/********************************************//**
* @file fichero.c
* @brief Descripcion del fichero
* @todo Describir la tarea pendiente
************************************************/
 Parámetro @image
Muestra en la documentación la imagen indicada. Requiere la definición del
IMAGE_PATH al directorio donde se alojará el fichero con la imagen. Se debe
especificar el formato de salida (HTML en este caso). Si deseamos generar una sección
específica (con una cabecera) para la imagen revisar la documentación del parámetro
@par.

18 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

/********************************************//**
* @file fichero.c
* @brief Descripcion del fichero
* @image html imagen.jpg
************************************************/
 Parámetro @par
Permite la creación de párrafos por parte del usuario, el siguiente ejemplo ilustra
múltiples combinaciones. Más información en la documentación oficial de Doxygen
(@par).

/********************************************//**
* Normal text.
*
* \par User defined paragraph:
* Contents of the paragraph.
*
* \par
* New paragraph under the same heading.
*
* \note
* This note consists of two paragraphs.
* This is the first paragraph.
*
* \par
* And this is the second paragraph.
*
* More normal text.
*/

 Parámetros especiales
A continuación se listan los parámetros complementarios para documentar código
ANSI-C.

@struct to document a C-struct.

@union to document a union.
@enum to document an enumeration type.
@fn to document a function.
@var to doc. a variable, typedef orenumvalue.
@def to document a #define.
@typedef to document a type definition.
@file to document a file.
@namespace to document a namespace.

19 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

 Crear nuestros propios parámetros

Si deseamos crear nuestro propio parámetro (etiqueta) debemos crear un alias en el
fichero de configuración de Doxygen.
En la sección Expert > Project > Aliases debemos incluir una sentencia para que
Doxygen identifique nuestro “nuevo” parámetro y sepa cómo tratarlo.

fixme=@todo
El texto del ejemplo se traduce (en el fichero de configuración) a

ALIASES = fixme=@todo
El ejemplo previo define un alias para la etiqueta @fixme que equivaldrá a @todo. Por
lo tanto los siguientes comentarios marcados con @todo y @fixme serán tratados de
la misma forma por Doxygen

/********************************************//**
* @file fichero.c
* @brief Descripcion del fichero
* @todo tarea pendiente 1
* @fixme tarea pendiente 2
************************************************/

 Crear nuestras propias secciones

Podemos crear nuevas sub secciones en la documentación (HTML navegable)
utilizando el parámetro @xrefitem. Generará sub secciones similares a TODO LIST.

req=@xrefitem req "Requirement\" "Requirements\"

El alias creado para @req generará una nueva sub sección en la documentación
(Related Pages > Requirements) así como una sección en la documentación del fichero
que estemos comentando denominada “Requirement” donde se alojará el comentario
que venga precedido por el “nuevo” parámetro @req.

/********************************************//**
* @file fichero.c
* @brief Descripcion del fichero
* @req Nuevo requisito
* @bug #35 Error
* @todo tarea pendiente
************************************************/
El ejemplo anterior ilustra la creación de la nueva sub sección en Related pages para
Requirements, donde incluirá el comentario detallado.
La sub sección Bug List, al igual que la sub sección de Todo List, están pre definidas por
Doxygen para poder trabajar con las etiquetas @bug y @todo respectivamente, por lo
que al incluir un comentario con la etiqueta, la sección se genera utomáticamente.

20 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

 Generar la documentación de subdirectorios de forma selectiva

Supongamos que disponemos de un directorio /src con el directorio de nuestro código,
que a su vez está organizado en múltiples directorios. Si deseamos generar
únicamente la documentación de algunos de esos directorios (no de todos) debemos
seleccionarlos de forma explícita en el apartado Expert > Input > Input del Doxygen
GUI frontend. Para lo cual añadiendo una ruta por cada una de los directorios
deseados.
Una alternativa, consiste en excluir ficheros o directorios con la etiqueta EXCLUDE
descrita en documentación de Doxygen.
 Reutilizar documentación ya existente
Es posible definir filtros que Doxygen ejecuta previo a la generación de la
documentación, para “traducir” los comentarios ya existentes a comentarios que
Doxygen pueda interpretar.
Para crear filtros debe configurarse la opción INPUT_FILTER.
En el siguiente ejemplo se define un filtro para procesar //FIXME como un el
parámetro \todo

INPUT_FILTER = "sed -e 's/\/\/.*FIXME/\/\/\/ \\todo/'"

Las sustituciones realizadas por Doxygen con los INPUT_FILTER no modifican los
ficheros de código y comentarios.
 Dar formato a los comentarios
La información de los comentarios se puede estructurar, organizar, presentar en listas,
etc . Para más detalle consultar el apartado Markdown support de la documentación
oficial de Doxygen.

 Experiencias de terceros
A continuación se proponen algunas recomendaciones y ejemplo de uso de Doxygen:
o RTEMS http://rtems.org/wiki/index.php/Doxygen_Recommendations
o Carnegie Mellon https://www.cs.cmu.edu/~410/doc/doxygen.html
o Stackoverflow question http://stackoverflow.com/questions/51667/best-tips-
for-documenting-code-using-doxygen

21 / 22
Trabajar con Doxygen MEJORA Y MANTENIMIENTO DE SISTEMAS EMBEBIDOS

6 PREGUNTAS FRECUENTES

Este apartado resuelve las principales cuestiones planteadas al comenzar a trabajar

con Doxygen en un entorno de programación en ANSI-C

 ¿Si los gráficos no se visualizan?

Comprobar que los parámetros HAVE_DOT, CALL_GRAPH y CALLER_GRAPH están
activados y que el parámetro DOT_PATH contiene la ruta al directorio bin de la
instalación de Graphviz.
 ¿Por qué no se muestra mi bloque de comentarios?
Comprobar la sintaxis utilizada para el comentario y contrastarla con las posibles
proporcionadas por Doxygen en la sección Comment blocks for C-like languages de la
documentación oficial. ¡Probablemente nos falte/sobre algún carácter!
 ¿Por qué no se muestran las imágenes añadidas en el proyecto?
Comprobar que el parámetro IMAGE_PATH contiene la ruta al directorio donde se
ubican los ficheros con las imágenes y asegurarse que en los comentarios hemos
añadido el parámeto @image donde deseamos que se muetre la imagen.
 ¿Por qué se muestra deshabilitado un gráfico (sin vínculo)?
Cuando los gráficos navegables generados por Doxygen (dot) nos muetran un nodo
deshabilitado (en gris y sin vínculo), significa que este fichero incluye un #include al
fichero que lo apunta pero no utiliza ninguna de sus funciones.

22 / 22