Doxygen

Tutorial

Resumen
Doxygen es una herramienta para generar documentación a partir
del código fuente. Es un sistema de documentación para C++, C, Ja-
va, ObjectiveC, Python, IDL (Corba and Microsoft flavors), Fortran,
VHDL, PHP, C#.

1
Índice
1. Instalación 4

2. Compilación 4

3. Comenzar 5

4. Crear un archivo de configuración 6

5. Generando la documentación 7
5.1. Salida HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.2. Salida LATEX . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.3. Salida RTF . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.4. Salida XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
5.5. Salida Man . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

6. Documentando el código 8

7. Bloques especiales de documentación 10

7.1. Documentando miembros . . . . . . . . . . . . . . . . . . . . 11

8. Documentación en otros sitios 13

9. Listas 13
9.1. Usando signos menos . . . . . . . . . . . . . . . . . . . . . . . 13
9.2. Usando comandos HTML . . . . . . . . . . . . . . . . . . . . 14

[Link] 15
10.1. Módulos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
10.2. Grupos de miembros . . . . . . . . . . . . . . . . . . . . . . . 15
10.3. Subpaginar . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
10.4. Incluı́r fórmulas . . . . . . . . . . . . . . . . . . . . . . . . . . 16

[Link]́ficos y diagramas 18

[Link]́n automática de links 18

12.1. Links a páginas web y direcciones de mail . . . . . . . . . . . 19
12.2. Links a archivos . . . . . . . . . . . . . . . . . . . . . . . . . 19
12.3. Links a funciones . . . . . . . . . . . . . . . . . . . . . . . . . 19
12.4. Links a variables, typedefs, enum types, enum values y defines 19
12.5. typedefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

2
[Link] 20
13.1. Alias simples . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
13.2. Alias con argumentos . . . . . . . . . . . . . . . . . . . . . . . 20
13.3. Anidando comandos . . . . . . . . . . . . . . . . . . . . . . . 21

[Link] a documentación externa 22

[Link] Especiales 24
15.1. Formato de texto . . . . . . . . . . . . . . . . . . . . . . . . . 24
15.2. Indicadores Estructurales . . . . . . . . . . . . . . . . . . . . 25
15.3. Indicadores de sección . . . . . . . . . . . . . . . . . . . . . . 27
15.4. Indicadores de links . . . . . . . . . . . . . . . . . . . . . . . 28
15.5. Bloques especiales de documentación en VHDL . . . . . . . . 29
15.6. Otros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

[Link] 30

3
1. Instalación
Primero necesita obtener la última versión de Doxygen de la página web:
[Link]
Además usted necesitará:

Las herramientas GNU flex, bison, GNU make y strip.

Para generar un Makefile necesitará perl.

El script de configuración asumirá que usted posee las herramientas

de Unix como sed, date, find, uname, mv, cp, cat, echo, tr, cd y rm.

Para hacer uso de todas las caracterı́sticas de Doxygen, deberá instalar tam-
bien las siguientes herramientas:

Una distribución de LATEX, por ejemplo teTeX 1.0, esto es necesario

para generar las salidas Latex, PostScript y PDF.

Graphviz, Graph visualization toolkit, versión 1.8.10 o mayor. Nece-

saria para incluı́r los gráficos.

Un intrprete de ghostscript.

Python para genera la documentación propia de doxygen.

2. Compilación
Compilación:
1. gunzip doxygen$[Link] descomprime el archivo.
2. tar xf doxygen$[Link] desempaqueta el archivo.
3. ejecute el script configure: sh ./configure
Para conocer todas las opciones para usar el configure ejecute:
configure help
Compile el programa ejecutando:
make
El programa deberı́a compilar sin problemas y tres binarios deberı́an
crearse en el directorio bin de la distribución.
Opcional: Generar el manual del usuario ejecutando:
make docs
Luego de compilar las fuentes ejecute un make install para instalar doxy-
gen.

4
3. Comenzar
El ejecutable doxygen es el programa principal que analiza el código y
genera la documentación.
El ejecutable doxytag es necesario solo si desea generar referencias a
documentación externa de la que no tiene las fuentes.
De manera opcional, puede ser usado el ejecutable doxywizard, que es
una interfaz grafica para editar el archivo de configuración.
El siguiente gráfico muestra la relación entre las herramientas y el flujo
de información entre ellas:

Figura 1: flujo de informacion

5
4. Crear un archivo de configuración
Doxygen usa un archivo de configuración para determinar todas sus op-
ciones. Cada proyecto deberı́a tener su propio archivo de configuración.
Para simplificar la creación de este archivo, doxygen puede crear uno con
el comando:
doxygen g configfile
donde <configfile>es el nombre del archivo de configuración, si se omite
el nombre del archivo, se creará uno llamado doxyfile. Si ya existe un archivo
con el mismo nombre, doxygen renombrará el actual a <configfile>.bak antes
de generar el nuevo.
El archivo de configuración tiene un formato similar al de un Makefile;
consiste en un numero de asignaciones (tags) de la forma:
TAGNAME = VALUE
Si comienza a usar doxygen para un proyecto existente, puede hacerse
una idea de como es la estructura y de como resultará la documentación
poniendo la tag EXTRACT ALL = YES.
Si no desea editar el archivo de configuración con un editor de texto,
puede usar doxywizard, una interfaz gráfica que puede crear, leer y editar los
archivos de configuración del doxygen de manera gráfica y sencilla.
Para pequeños proyectos de pocos C/C++ fuentes y headers, puede dejar
la tag INPUT vacı́a y doxygen buscará por fuentes en el directorio actual.
Si tiene un proyecto mas grande debe asignar los directorios o directorio
raı́z a la tag INPUT, y agregar uno o mas patrones de archivos (*.c, *.h,
etc.)a la tagFILE PATTERNS . Sólo los archivos que coinciden con estos
patrones serán analizados. Para un análisis recursivo de un árbol de fuentes,
la tagRECURSIVE debe tener valor YES.

6
5. Generando la documentación
Para generar la documentación debe ingresar:
doxygen configfile
Dependiendo de sus opciones, doxygen creará los directorios html, rtf,
latex, xml y/o man.
El directorio de salida por defecto es en el que doxygen se ha iniciado. El
directorio raiz en el cual se escribe la salida de doxygen puede modificarse
usando
OUTPUT DIRECTORY . El directorio especifico de formato dentro del
directorio de salida puede ser seleccionado usando las HTML OUTPUT,
RTF OUTPUT,
LATEX OUTPUT, XML OUTPUT, y MAN OUTPUT tags del archivo
de configuración.

5.1. Salida HTML

La documentación HTML generada puede verse apuntando un browser
html al archivo [Link] en el directorio html. Para mejores resultados
es mejor utilizar un browser con soporte para CSS. Algunas caracterı́sticas
comoGENERATE TREEVIEW requieren de un browser con soporte para
DHTML y Javascript. Si tiene planeado usar el buscador (tag SEARCHEN-
GINE), debe ver la salida html via un web server que soporte PHP (ej:apache
con el modulo PHP instalado).

5.2. Salida LATEX

La documentación latex generada debe ser compilada anteriormente por
un compilador latex. Para simplificar el proceso de compilación, doxygen
crea un Makefile dentro del directorio latex. Los contenidos del Makefile
van a depender de las opciones de USE PDFLATEX, si está deshabilitado,
tipeando make en el directorio latex generará un archivo dvi llamado ref-
[Link]. Este archivo puede verse usando xdvi o convertirlo a PostScript
[Link] tipeando make ps (esta acción requiere la herramienta dvips).
También es posible convertir los archivos a PDF si tiene instalado el intér-
prete de ghostscript, con el comando make pdf (o make pdf 2on1 ). Para obte-
ner mejores resultados en la salida PDF deberia setear los tagsPDF HYPERLINKS
y USE PDFLATEX en yes. En este caso el Makefile contendra sólo el destino
para construir [Link] directamente.

5.3. Salida RTF

Doxygen combina la salida RTF a un único archivo llamado [Link].
Este archivo es optimizado para importar desde Microsoft Word. Cierta

7
información es codificada usando campos. Para mostrar el valor real usted
necesita seleccionar todo (Edit Select All) y luego alternar campos.

5.4. Salida XML

La salida XML consiste de dump estructurado de información reunida
por doxygen. Cada componente tiene su propio archivo XML y tambn existe
un archivo index llamado [Link].
Un archivo XSLT llamado [Link] tambin es generado y puede ser
usado para combinar todos los archivos XML a un único archivo.
Doxygen tambin genera dos archivos esquema XML [Link] (para el
archivo index) [Link] (para los archivos de componentes). Este archivo
de esquemas describe los posibles elementos, sus atributos y como están
estructurados.

5.5. Salida Man

las paginas de manual generadas pueden verse utilizando el programa
man. Debe asegurarse que el directorio man este en el man path (ver la
variable de entorno MANPATH).

6. Documentando el código
Si la opción EXTRACT ALL tiene el valor NO en el archivo de confi-
guración (opción por defecto), doxygen sólo generará documentación para
miembros documentados, archivos, clases, etc. Para documentar hay dos
opciones:

Colocar un bloque especial de documentación delante de la declaración

o definición de los miembros, clases, etc.

Colocar un bloque especial en algún otro lugar (otro archivo u otra

ubicación) y poner un “comando estructural” en el bloque de documen-
tación. Un comando estructural enlaza un bloque de documentación a
una cierta entidad que puede ser documentada.

Los archivos solo pueden ser documentados de la segunda forma. Las fun-
ciones, variables, typedefs, defines, no necesitan un comandodas las lı́neas
vacı́as resultantes son tratadas como separadores de párrafos.
Esto evita que se deban agregar comandos de nuevo párrafo para lograr
una documentación mas legible.
· Los links son creados para palabras que corresponden a clases documen-
tadas (a menos que la palabra es precedida por %, en este caso la palabra
no será enlazada y el signo % será eliminado).

8
 · Los links a miembros son creados cuando se encuentran ciertos patrones
en el texto.
· Los marcadores HTML que están en la documentación son interpretados
y transformados en equivalente.

9
7. Bloques especiales de documentación
Es un bloque de documentación de C o C++ con algunas marcas adi-
cionales, ası́ doxygen puede reconocerlo y generar su documentación.
Para cada ı́tem del código existen dos ( a veces tres) tipos de descripcio-
nes que juntas forman la documentación: una descripción brief (breve) de
una lı́nea y una descripción detailed (detallada) mas extensa. Para todos y
funciones tambin existe una descripción llamada in body (en cuerpo), que
consiste en la concatenación de todos los bloques de documentación encon-
trados en el cuerpo de la función.
Existen varias formas de marcar un bloque de comentario como una
descripción detallada:
JavaDocs alternativa es usar un bloque de al menos dos lineas de comen-
tarios de C++, donde cada lı́nea comienza con un / o ! adicional

///
/// comentarios.
///

o bien

//!
//! comentarios
//!

Para aquellos a quienes desean comentarios mas visibles en la documen-

tación pueden utilizar:

/******************************//**
*.comentarios..
*********************************/

o bien

//////////////////////////////////
/////comentarios..
//////////////////////////////////

10
Para las descripciones breves (brief) tambin existen varias posibilidades:
Puede usar el comando\brief con alguno de los bloques de comentarios
anteriores.
Este comando termina al final del párrafo, ası́ la descripción detallada
continúa luego de una lı́nea en blanco.
/*!\brief descripción breve.
* continua la descripción brermina en el primer punto seguida de un
espacio o una nueva lı́nea.

/** Descripción breve que termina aquı́. Descripción

* detallada continua aquı́.
*/

o bien

/// Descripción breve que termina aquı́. Descripción detallada

/// continua aquı́.

Doxygen sólo permite una descripción breve y una detallada.

7.1. Documentando miembros

Si desea documentar los miembros de un archivo, estructura, union, class
o enum debe colocar un marcador <en el bloque:

int var; /*!< descripción después del miembro */

int var; /**< descripción detallada después del miembro */

int var; //!<descripción detallada después del miembro

//!<

int var; ///< descripción detallada después del miembro

///<

Generalmente se deseará colocar una describpción breve luego de un

miembro, esto se realiza de la siguiente manera:

int var; //!< descripción breve después del miembro

11
O bien

int var; ///< Descripción breve después del miembro

Nótese que estos bloques tienen la documentación de los miembros de-

lante de la definición (incluyendo funciones globales). De sta manera la do-
cumentación puede ser ubicada en el archivo fuente en lugar del archivo
header. Esto permite que el archivo de headers quede compacto, y permite
a los implementadotes de los miembros un acceso mas directo a la documen-
tación.
Tambien las descripciones breves pueden situarse antes de la declaración
y la descripción detallada antes de la definición del miembro.
Éstos bloques solo pueden ser utilizados para documentar miembros o
parámetros, no pueden ser usados para documentar archivos, clases, unio-
nes, estructuras, grupos, namespaces y enums. Por lo tanto, los comandos
estructurales mencionados en la próxima sección (como \class) son ignorados
dentro de stos bloques de comentarios.

12
8. Documentación en otros sitios
Hasta ahora hemos asumido que los bloques de documentación están
siempre ubicados al frente de una declaración o definición de un archivo,
clase o namespace o delante o detrás de un miembro. Puede haber ocasiones
en las que se desee comentar en otros sitios.
Doxygen le permite colocar bloques de documentación prácticamente en
cualquier sitio, la excepción es dentro del cuerpo de una función o dentro de
un bloque de comentarios normal en C style.
Lo que se necesita es un comando estructural dentro del bloque de do-
cumentación, lo que conlleva a algunas duplicaciones de información. Por lo
tanto en la práctica es recomendable evitarstos comandos a menos que otros
requerimientos lo fuercen.
Los comandos estructurales (como todos los otros comandos) comienzan
con un backslash (\), o un arroba ()
Para documentar una función global en C, typedef, enum o definición del
preprocesador, primero debe documentar el archivo que lo contiene (usual-
menteste será un archivo header).

9. Listas
Doxygen provee varias maneras de crear listas de ı́tems:

9.1. Usando signos menos

Colocando una cantidad de signos menos () alineados en una columna al
principio de la lı́nea generarán automáticamente una lista. Las listas nuricas
tambien pueden ser generadasusando un signo menos seguido por un sı́mbolo
numeral (#). Es posible anidar listas indentando los ı́tems.
Si utiliza tabs para la indentación dentro de listas, por favor asegúrese
que TAB SIZE en el archivo de configuración tenga puesto el valor correcto.
Puede finalizar una lista comenzando un nuevo párrafo o colocando un
punto (.) en una lı́nea vacı́a en el mismo nivel de indentación que la lista
que desea terminar.
Veamos un ejemplo:

/**
* Texto anterior a la lista
* - item lista 1
* - sub item 1
* - sub sub item 1
* - sub sub item 2

13
 * .
* El punto de arriba significa que termina la lista
* de sub sub items.
* Mas texto del primer sub item.
* .
* El punto de arriba termina la lista de sub items.
* Mas texto para el primer item de la lista.
* - sub item 2
* - sub item 3
* - list item 2
* .
* Mas texto en el mismo parrafo.
*
* Mas texto en un nuevo parrafo.
*/

9.2. Usando comandos HTML

Si lo desea puede usar comandos HTML dentro de los bloques de docu-
mentación. Utilizar estos comandos tiene la ventaja de ser un mtodo más
natural para los ı́tems de listas que consisten de múltiples párrafos.

14
10. Agrupar
Doxygen posee tres mecanismos para agrupar. Un mecanismo trabaja a
nivel global, creando una nueva página para cada grupo. Estos grupos son
llamados modulos en la
documentación. El segundo mecanismo trabaja dentro de una lista de
miembros de alguna entidad compuesta y es llamado grupos de miembros
(member groups). Para las páginas existe un tercer mecanismo llamado sub-
paginar (subpaging).

10.1. Módulos
Módulos es una manera de agrupar cosas en páginas separadas. Se puede
documentar un grupo como un todo, ası́ tambin como todos los miembros
individuales. Los miembros de un grupo pueden ser archivos, namespaces,
clases, funciones, variables, enums, typedefs y defines, pero tambin otros
grupos.
Para definir un grupo debe colocarse el comando \defgroup en un blo-
quero de un grupo especı́fico colocando un comando \ingroup dentro de su
bloque de documentación.
Para evitar colocar comandos \ingroup en la documentación por cada
miembro, se puede agrupar miembros abriendo un marcador antes del grupo
y el marcador de cierre despus del grupo.
Los grupos tambin pueden ser anidados usando stos marcadores de gru-
pos.

10.2. Grupos de miembros

Si un compuesto (clase o archivo) tiene muchos miembros, es usualmente
deseado agruparlos.
Un grupo de miembros es definido de la siguiente manera:

//@\{

\...

//@}

bloque ó

/*@{*/

\...

15
/*@}*/

Antes de abrir un marcador de bloque, puede colocarse un bloque de comen-

tarios separado. Este bloque debe contener el comando name (o \name) y
se utiliza para especificar el encabezado del grupo.
No está permitido el anidamiento de grupos de miembros.

10.3. Subpaginar
La información puede ser agrupada en páginas usando los comandos
\page y \mainpage.
Normalmente, esto resulta en una lista plana de páginas, donde la página
main es la primera en la lista.

10.4. Incluı́r fórmulas

Doxygen permite agregar fórmulas a la salida (funciona solamente para
las salidas y HTML).
Son necesarias las siguientes herramientas:

LATEX: el compilador de LATEX.

Dvips: Una herramienta para convertir archivos DVI a archivos PostS-

cript.

Gs: el intrprete GhostScript para convertir archivos PostScript a bit-

maps.
Existen tres formas de incluir fórmulas en la documentación:

1. Utilizando fórmulas que aparecen en el texto en una lı́nea. Éstas fór-

mulas deben colocarse entre un par de comandos \f$ como por ejemplo:

La distancia entre \f$(x_1,y_1)\f$ y \f$(x_2,y_2)\f$

es \f$\sqrt{(x_2x_1)^2+(y_2y_1)^2}\f$.

La salida se verá ası́:

p
La distancia entre (x1 , y1 ) y (x2 , y2 ) es (x2 x1 )2 + (y2 y1 )2 .

2. Fórmulas no numéricas en lı́neas separadas deben colocarse entre los

comandos \f[ y \f]
por ejemplo:

16
 \f[
|I_2|=\left| \int_{0}^T \psi(t)
\left\{
u(a,t)
\int_{\gamma(t)}^a
\frac{d\theta}{k(\theta,t)}
\int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
\right\} dt
\right|
\f]

La salida se verá ası́:

RT n Ra o
dθ R θ
|I2 | = 0 ψ(t) u(a, t) γ(t) k(θ,t) a c(ξ)ut (ξ, t) dξ dt

3. Las fórmulas u otros elementos de que no son del ambiente matemáti-

co pueden ser especificados usando el comando \fenvironment, donde
environment es el nombre del ambiente de , el fin del comando es \f} .
Veamos un ejemplo, equation array:

\f{eqnarray*}{

g &=& \frac{Gm_2}{r^2} \\
&=& \frac{(6.673 \times 10^{11}\,\mbox{m}^3\,
\mbox{kg}^{1}\,
\mbox{s}^{2})(5.9736 \times 10^{24}\,
\mbox{kg})}{(6371.01\,\mbox{km})^2} \\
&=& 9.82066032\,\mbox{m/s}^2
\f}

La salida se verá ası́:

Gm2
g= r2
(6,673×10−11 m3 kg s−2 )(5,9736×1024 kg)
−1
= (6371,01 km)2
2
= 9,82066032 m/s

17
11. Gráficos y diagramas
Doxygen puede crear gráficos, generados por la herramienta dot de Graph-
viz ([Link] La generación de gráficos en Doxygen gene-
ralmente se realiza automaticamente basada en las opciones del archivo de
configuración. Estas opciones con excepción de DOT PATH pueden tener
los valores YES o NO. Estas son opciones globales para el proyecto. Los grá-
ficos sólo serán generados si la herramienta dot está instalada, y la opción
HAVE DOT está en YES en el archivo de configuración.

HAVE DOT indica que la herramienta dot está disponible.

DOT PATH es el ”path.a la herramienta dot, si no está en $PATH.

GRAPHICAL HIERARCHY generará una representación grafica de

la jerarquı́a del código. Actualmente está solo disponible en HTML.

INCLUDE GRAPH generará un gráfico por cada archivo documen-

tado que incluya al menos un archivo más. Esta caracterı́stica está
disponible sólo para HTML y RTF.

CALL GRAPH generará un gráfico por cada función, sus llamadas, y

las llamadas a ésta. Ası́mismo si CALLER GRAPH está en YES se
crearán los gráficos mostrando por quien son llamadas las funciones.

CALLER GRAPH generará gráficos que indica las funciones llamadas

por la función documentada.

COLLABORATION GRAPH generará un gráfico por cada clase do-

cumentada y estructura que muestre las relaciones de uso con otras
estructuras.
También se puede utilizar la sintaxis de dot para generar un gráfico.
Los comandos especı́ficos de dot deben estar entre los comandos \dot
y \enddot.

12. Generación automática de links

La mayorı́a de los sistemas de documentación tienen una sección espe-

cial ”see also”(vea también), donde pueden insertarse links a otras par-
tes de la documentación. Además de que Doxygen posee un comando
para comenzar una sección ası́ (vea \sa), permite colocar esta clase de
links en caulquier parte de la documentación. Para la documentación
en LATEX, en lugar de un link se escribe el número de página. Ade-
más el ı́ndice al final del documento puede utilizarce para encontrar
rapidamente la documentación de una clase, miembro, namespace o

18
archivo. Para las páginas man no se generan referencias. Las próximas
secciones muestran como generar links a las entidades documentadas
en un archivo fuente.

12.1. Links a páginas web y direcciones de mail

Doxygen reemplazará automáticamente las URLs y direcciones de mail

que encuentre en la documentación por links (en HTML).

12.2. Links a archivos

Todas las palabras que contengan un punto (.) que no sea el último
caracter de la palabra son considerados nombres de archivos. Si la pa-
labra es el nombre de un archivo documentado de entrada, se generará
automáticamente un link a la documentación de ese archivo.

12.3. Links a funciones

Se crearán links a funciones si es encontrado uno de los siguientes

patrones:

1. <functionName>"("<argument-list>")"
2. <functionName>"()"
3. "::"<functionName>
4. (<className>"::")n<functionName>"("<argument-list>")"
5. (<className>"::")n<functionName>"("<argument-list>")"<modifiers>
6. (<className>"::")n<functionName>"()"
7. (<className>"::")n<functionName>
con n>0

12.4. Links a variables, typedefs, enum types, enum va-

lues y defines

Todas éstas entidades pueden ser referidas de la misma manera que

se explica en la sección anterior. Para mayor claridad es recomendable
utilizar los patrones 3 y 7 en éste caso.

12.5. typedefs

Los typedefs que involucran clases, estructuras y uniones, como ty-

pedef struct StructName TypeName, crean un alias para StructName,
entonces se crearán links para StructName, cuando StructName mismo
o TypeName son encontrados.

19
13. Comandos
Doxygen provee un gran número de comandos especiales, comandos
XML y comandos HTML, que pueden ser usados para realzar o es-
tructurar la documentación dentro de un bloque de comentario. Si por
alguna razón existe la necesidad de definir un nevo comando, se puede
utilizar una definicion ALIAS. La definición de un alias debe ser espe-
cificada en el archivo de configuración usando el tag de configuración
ALIASES.

13.1. Alias simples

La forma mas simple de un alias es la sustitución simple de la forma:

name=value
Por ejemplo:

ALIASES += sideeffect="\par Side Effects:\n"

esto permitirá poner el comando \sideefect en la documentación, que

resultará en un párrafo definido por el usuario con encabezado Side
Effects: Nótese que puede colocar \n en la parte del valor de un alias
para insertar una nueva lı́nea.

13.2. Alias con argumentos

Los alias pueden tener uno o más argumentos. En la definición del

alias se necesitan un número especı́fico de argumentos entre llaves. En
la parte del valor de la definición se pueden colocar marcadores \x,
donde x representa el número de argumento empezando por 1. Por
ejemplo:

ALIASES += l{1}="\ref \1"

Dentro de un bloque de comentarios:

/** See \l{SomeClass} for more information. */

ó

/** See \ref SomeClass for more information. */

ALIASES += l{1}="\ref \1"

20
ALIASES += l{2}="\ref \1 \"\2\""

/** See \l{SomeClass,Some Text} for more information. */

Dentro de un bloque de comentarios se expanderá a:

/** See \ref SomeClass ”Some Text”for more information. */
donde el comando con un sólo argumento seguirá funcionando como
se muestra anteriormente.
Alias también pueden expresarse en términos de otros alias. Ejemplo
un nuevo comando \reminder puede ser expresado como \xrefitem por
un comando intermediario \xreflist:

ALIASES += xreflist{3}="\xrefitem \1 \"\2\" \"\3\" " \

ALIASES += reminder="\xreflist{reminders,Reminder,Reminders}" \

Para alias con mas de un argumento se utliza la coma como separador.

Si se desea poner una coma dentro del comando necesitará usar un
backslash, ejemplo:
\lSomeClass,Some text\, with an escaped comma

13.3. Anidando comandos

Puede utilizar comandos como argumentos de alias, incluyendo coman-

dos definidos utilizando alias, ej:

ALIASES += Bold{1}="<b>$\backslash$1</b>"
ALIASES += Emph{1}="<em>$\backslash$1</em>"

dentro de un bloque de comentarios:

/** This is a $\backslash$Bold{bold $\backslash$Emph{and} Emphasized}

text fragment. */

y se expandirá de la siguiente manera:

/** This is a <b>bold <em>and</em> Emphasized</b> text fragment. */

21
14. Links a documentación externa

Si su proyecto depende de librerı́as externas o herramientas, hay varias

razones por las cuales no incluı́r todas la fuentes en cada pasada de
doxygen.
<++>Espacio en disco: Alguna documentación puede estar dis-
ponible fuera del directorio de salida de doxygen, por ejemplo
en algún lugar de la web. Si lo desea, puede vincular a estas
páginas en lugar de generar la documentación en su directorio
local de salida. Velocidad de Compilación: Los proyectos exter-
nos suelen tener una frecuencia de actualización diferente a las
de su propio proyecto. No tiene mucho sentido dejar que doxygen
analice las fuentes de éstos proyectos externos una y otra vez, in-
cluso si nada ha cambiado. Memoria: Para árboles muy grandes
de código fuente, permitir que doxygen analice todas las fuentes
puede tomar demasiado de la memoria del sistema. Dividiendo
las fuentes en varios ”packages”, las fuentes de un paquete puede
ser analizadas por doxygen, mientras que todos los otros ”packa-
ges”que dependen de este paquete, estan linkeados externamente.
Esto ahorra una gran cantidad de memoria. Disponibilidad: Pa-
ra algunos proyectos que están documentados con doxygen, las
fuentes pueden simplemente no estar disponibles. Cuestiones de
derecho de autor: Si el paquete externo y su documentación tiene
derechos de autor de otra persona, tal vez sea mejor - o incluso
necesario - referenciarlo en lugar de incluir una copia del mismo
con la documentación de su proyecto. Cuando el autor prohı́be la
redistribución, esto es necesario. Si el autor exige el cumplimiento
de alguna condición de licencia como condición de redistribución,
y usted no quiere que se obligan a cumplir con esas condiciones,
en referencia a su copia de su documentación es preferible a que
se incluya una copia.

Si se aplican algunas de las razones anteriores, puede utilizar el me-

canismo de archivo de marcadores (tag file) de doxygen. Un tag file
es una representación compacta de las entidades encontradas en las
fuentes externas. Doxygen puede leer y generar tag files.
Para generar un tag file debe poner el nombre de un tag file a conti-
nuación de la opción GENERATE TAGFILE en el archivo de confi-
guración.
Para combinar la salida de uno o mas proyectos externos con el propio,
debe especificar el nombre de los tag files a continuación de la opción
TAGFILES en el archivo de configuración.

22
Un tag file no contiene información sobre dónde se encuentra la docu-
mentación externa. Ésto podrı́a ser un directorio o una URL. Entonces
cuandos e incluye un tag file, debe especificar el lugar en que se en-
cuentran. Existen dos formas de hacer esto:

• En tiempo de configuración: Sólo asigne el lugar de salida al tag

file especificado en la opción TAGFILES. Si usa un path realativo,
debe ser relativo respecto del directorio donde la salida HTML
de su proyecto es generada.
• Luego de la compilación: Si no asigna un lugar a el tag file, doxy-
gen generará dummy links para todas las referencias HTML ex-
ternas. También generará un script de perl llamado installdox en
el directorio de salida HTML. Éste script debe ejecutarse para re-
emplazar los dummy links por links reales para todos los archivos
HTML generados.

En algunos (excepcionales) casos puede tener la documentación gene-

rada por doxygen, pero no los fuentes ni los tag files. En este caso puede
usar la herramienta doxytag para extraer un tag file de los HTML ge-
nerados. Otro caso en el que debe usar doxytag es si desea crear un
tag file para la documentación Qt.
La herramienta doxytag depende de la estructura particular de la sa-
lida generada y de algunos marcadores especiales que son generados
por doxygen. Ya que ésta clase de extracción es frágil y susceptible a
errores es recomendable que sea usada en caso de que no exista otra
alternativa.

23
15. Comandos Especiales
Todos los comandos en la documentación comienzan con un backslash
(\)o un arroba (@). Algunos comandos tienen uno o mas argumentos.
Cada argumento tiene un cierto rango:

• si <>entonces el argumento es una sola palabra.

• si () entonces el argumento se extiende hasta el final de la lı́nea.
• si entonces el argumento se extiende hasta el próximo párrafo.
Los párrafos están delimitados por una lı́nea en blanco o por un
indicador de sección.
• si [] entonces significa que el argumento es opcional.

Acontinuación se detalla una lista de los comandos más usados:

15.1. Formato de texto

• \a <palabra> escribe palabra en una fuente [Link]
a \e.
• \arg <palabra> item de una lista, equivalente a .
• \b <palabra> escribe palabra en negrita.
• \c <palabra> escribe palabra en la fuente typewriter.
• \code Comienza una sección de bloque de código.
• \endcode Finaliza una sección de bloque de código (\code).
• \copydoc ref Copia documentación de ref.
• \dot Comienza un bloque de gráfico dot.
• \enddot Finaliza un bloque de gráfico dot.
• \f$ Comienza y finaliza una fórmula de una lı́nea.
• \f[ Comienza un bloque de fórmula centrada.
• \f ] Finaliza un bloque de fórmula centrada.
• \image <formato><archivo>caption Coloca una imagen
dentro de la documentacion con la caption çaption”.
• \htmlonly Comienza un bloque para salida HTML únicamente.
• \endhtmlonly Finaliza un bloque para salda HTML únicamen-
te.
• \n Fuerza una nueva lı́nea.
• \verbatim Comienza un bloque incluı́do como textual.
• \endverbatim Finaliza un bloque textual(\verbatim).

24
15.2. Indicadores Estructurales
• \ addtogroup <nombre>[(titulo)] Define un grupo igual que
\defgroup, pero en contraste, usando <nombre>mas de una vez
no resultara en un warning, sino en un grupo con la documenta-
cion combinada y el primer titulo que encuentre en alguno de los
comandos. El titulo es opcional, por lo tanto este comando tam-
bien puede ser utilizado para agregar un numero de entidades a
un grupo existente usando @ y @.
• \callgraph Cuando este comando es colocado en un bloque de
comentarios de una funcion y HAVE DOT esta en Yes, doxygen
generara un grafico de llamadas para esa funcion. El grafico sera
generado a pesar del valor que tenga CALL GRAPH.
• \callergraph Cuando este comando es colocado en un bloque de
comentarios de una funcion, y HAVE DOT esta en Yes, doxy-
gen generara un grafico de llamador de funciones para esa fun-
cion. El grafico sera generado a pesar del valor que tenga CA-
LLER GRAPH.
• \class <nombre>[<archivo-header>] [<nombre-header>]
Indica que un bloque de comentarios contiene documentacion pa-
ra una clase con el nombre <nombre>.
• \def <nombre> Indica que un bloque de comentarios contiene
documentacion para un macro #define.
• \defgroup <l><t> Define un grupo de módulo con etiqueta 1
y tı́tulo t.
• \enum <nombre> Indica que un bloque de comentarios contie-
ne documentacion para una enumeracion con nombre <nombre>.
• \example <nombre-archivo> Indica que un bloque de comen-
tarios contiene documentacion de un ejemplo de codigo fuente. El
nombre del archivo fuente es <nombre-archivo>. EL texto de este
archivo sera incluido en la documentacion, inmediatamente des-
pues de la documentacion contenida en el bloque de comentarios.
Todos los ejemplos son colocados en una lista. Puede incluirse
parte del path en <nombre-archivo>en el caso de que el nombre
no sea unico. Si es necesario mas de un archivo fuente para el
ejemplo, puede utilizarse el comando \include.
• \file [<nombre>] Indica que un bloque de comentarios contiene
documentacion para un fuente o archivo header con el nombre
<nombre>. El archivo puede incluir (parte de) el “path” si no
es unico. Si el nombre del archivo es omitido, entonces el bloque
de documentacion que contiene el comando \file pertenecera al
archivo en el que se encuentra. Importante: La doucmentacion de

25
 funciones globales, variables, typedefs y enum solo seran incluidas
en la salida si el archivo en el que se encuentran tambien esta
documentado.
• \fn (declaracion de funcion) Indica que un bloque de comen-
tarios contiene documentacion de una funcion. Este comando solo
es necesario si un bloque de comentarios no se encuentra delante o
detras de la declaracion o definicion de la funcion. Si el bloque de
comentarios esta delante de la declaracion, este comando puede
(y para evitar redundancia deberia) ser omitido. Una declaracion
de funcion completa, incluyendo argumentos debe ser especifica-
da a continuacion del comando en una sola linea. Importante: No
use este comando a menos que sea absolutamente necesario, ya
que lleva a la duplicacion de informacion, y en consecuencia a
errores.
• \hideinitializer Oculta el valor por defecto de #define.
• \ingroup <l1>[<l2>] Agrega documentacion al grupo [Link]-
tiples grupos pueden ser usados.
• \interface <n> Bloque de documentaciön para la interface n.
• \internal Todo el texto a continuación es sustraı́do hasta el final
del bloque de comentarios.
• \mainpage (t) El bloque de documentación del main o index.
• \name (header) Bloque de documentación de grupo de miem-
bros.
• \nosubgrouping Desactiva el subagrupamiento (subgrouping).
• \overload (s) Utilizado para documentar una funcion overloaded
con firma s.
• \package <n> Un bloque de documentación para el package n.
• \page <n>(t) Indica un bloque de documentación de un grupo
de página con etiqueta n y tı́tulo t.
• \showinitializer Muestra el valor por defecto de define.
• \struct <n> Bloque de documentación para una estructura n.
• \typedef (t) Bloque de documentación para un typedef t.
• \union <n> Bloque de documentación para la union n.
• \var (v) Bloque de documentación para la variable v.
• \weakgroup <n> Equivalente a \addtogroup pero tiene menor
prioridad en la resolución de conflictos de grupos.

26
15.3. Indicadores de sección
• \attention ... Comienza un párrafo de Atención.
• \author loa Incluye la lista de autores loa.
• \brief ... Una breve descripción del elemento.
• \bug ... Descripción de un bug.
• \cond <sec> Comienza una sección condicional.
• \date ... Incluye la fecha.
• \deprecated ... Comienza un párrafo desaprobado.
• \else Cláusula adicional al comando \if.
• \elseif <sec> Cláusula adicional al comando \cond.
• \endcond Finaliza una sección condicional.
• \endif Finaliza una cláusula \if.
• \exception <e> Comienza una descripción de la excepción para
e.
• \if <sec> Comienza una sección condicional.
• \ifnot <sec> Comienza una sección condicional.
• \invariant ... Comienza una decripción de un invariant.
• \note ... Comienza un párrafo de notas.
• \par (t) ... Comienza un párrafo con un tı́tulo opcional t.
• \param <p>... Comienza una descripción del parámetro p.
• \post ... Comienza una descripción de una post-condición.
• \pre ... Comienza una descripción de una pre-condición.
• \remarks ... Comienza un párrafos de observaciones.
• \return ... Comienza una descripción de valores de retorno.
• \retval <f>... Describe el valor de retorno de una función f.
• \sa ref Comienza un párrafo See Also.
• \see ref Equivalente a \sa.
• \since ... Describe desde cuando una entidad estuvo disponible.
• \test ... Comienza un párrafo de descripción ”test case”.
• \throw <e>... Equivalente a excepción.
• \todo ... Comienza un párrafo To Do.
• \version ... Comienza un párrafo donde puede ingresar la ver-
sión.
• \warning ... Comienza un párrafo para mensajes de alerta.
• \xrefitem <k>(h) . Crea un párrafo cross-referenced.

27
15.4. Indicadores de links
• \addindex (t) Agrega t al index de LATEX.
• \anchor (w) Coloca un anchor invisible w en el documento.
• \endlink Finaliza un link.
• \link <n>... Crea un link a n con texto especificado por el
usuario.
• \ref <n>(t) Crea una referencia a n con texto t.
• \subpage <n>(t) Crea una sub-página de nombre n.
• \section <l>(t) Crea una sección en una página con etiqueta 1
y tı́tulo t.
• \subsection <l>(t) Crea una sub-sección en una página con
etiqueta 1 y tı́tulo t.
• \paragraph <n>(t) Crea un párrafo en una página con etique-
ta 1 y tı́tulo t.

28
15.5. Bloques especiales de documentación en VHDL

Para VHDL un comentario comienza normalmente con "--". Doxygen

extraerá los comentarios que comiencen con "--!". Existen solo dos
tipos de bloques de comentarios en VHDL; de una lı́nea "--!" que re-
presenta una descripción breve, y de más de una linea, hay que repetir
"--!" por cada lı́nea representa una descripción detallada.
Los comentarios siempre se ubican delante del ı́tem a documentar, con
una excepción: para puertos el comentario puede también ir después
del ı́tem, y luego es tratado como una descripción breve del puerto.
Aquı́ sigue un ejemplo de un archivo en VHDL con comentarios Doxy-
gen:

-------------------------------------------------------
--! @file
--! @brief 2:1 Mux using with-select
-------------------------------------------------------

--! Use standard library

library ieee;
--! Use logic elements
use ieee.std_logic_1164.all;

--! Mux entity brief description

--! Detailed description of this

--! mux design element.
entity mux_using_with is
port (
din_0 : in std_logic; --! Mux first input
din_1 : in std_logic; --! Mux Second input
sel : in std_logic; --! Select input
mux_out : out std_logic --! Mux output
);
end entity;

--! @brief Architure definition of the MUX

--! @details More details about this mux element.
architecture behavior of mux_using_with is
begin
with (sel) select
mux_out <= din_0 when ’0’,
din_1 when others;

29
end architecture;

Para obtener una salida apropiada debe setear la opción OPTIMI-

ZE OUTPUT VHDL en YES en el archivo de configuración de Doxy-
gen.

15.6. Otros
• \ % Este comando escribe el simbolo % a la salida.
• \>+ Este comando escribe el simbolo > a la salida.
• \<+ Este comando escrible el sı́mbolo < a la salida.
• \# Este comando escribe el sı́mbolo # a la salida.
• \$ Este comando escrible el sı́mbolo $ a la salida.
• \& Este comando escribe el simbolo & a la salida.

16. Referencias

La información anterior se extrajo y tradujo del manual de Doxygen.

[Link]
Cecilia Chialchia -
ceciliach@[Link]

30