PDF de programación - Doxygen Tutorial

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

2. Compilación

3. Comenzar

4. Crear un archivo de configuración

5. Generando la documentación

5.1. Salida HTML . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2. Salida LATEX . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3. Salida RTF . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4. Salida XML . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.5. Salida Man . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6. Documentando el código

7. Bloques especiales de documentación

7.1. Documentando miembros

. . . . . . . . . . . . . . . . . . . .

8. Documentación en otros sitios

9. Listas

9.1. Usando signos menos . . . . . . . . . . . . . . . . . . . . . . .
9.2. Usando comandos HTML . . . . . . . . . . . . . . . . . . . .

10.Agrupar

10.1. Módulos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2. Grupos de miembros . . . . . . . . . . . . . . . . . . . . . . .
10.3. Subpaginar
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.4. Incluír fórmulas . . . . . . . . . . . . . . . . . . . . . . . . . .

11.Gráficos y diagramas

4

4

5

6

7
7
7
7
8
8

8

10
11

13

13
13
14

15
15
15
16
16

18

12.Generació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

13.Comandos

13.1. Alias simples
. . . . . . . . . . . . . . . . . . . . . . . . . . .
13.2. Alias con argumentos . . . . . . . . . . . . . . . . . . . . . . .
13.3. Anidando comandos
. . . . . . . . . . . . . . . . . . . . . . .

14.Links a documentación externa

15.Comandos Especiales

15.1. Formato de texto . . . . . . . . . . . . . . . . . . . . . . . . .
15.2. Indicadores Estructurales
. . . . . . . . . . . . . . . . . . . .
15.3. Indicadores de sección . . . . . . . . . . . . . . . . . . . . . .
15.4. Indicadores de links
. . . . . . . . . . . . . . . . . . . . . . .
15.5. Bloques especiales de documentación en VHDL . . . . . . . .
15.6. Otros
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

16.Referencias

20
20
20
21

22

24
24
25
27
28
29
30

30

3

1.

Instalación

Primero necesita obtener la última versión de Doxygen de la página web:
http://www.doxygen.org
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$VERSION.src.tar.gz descomprime el archivo.
2. tar xf doxygen$VERSION.src.tar 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

1

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 index.html 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-
man.dvi. Este archivo puede verse usando xdvi o convertirlo a PostScript
refman.ps 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 refman.pdf directamente.

5.3. Salida RTF

Doxygen combina la salida RTF a un único archivo llamado refman.rtf.
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 index.xml.

Un archivo XSLT llamado combine.xslt tambin es generado y puede ser

usado para combinar todos los archivos XML a un único archivo.

Doxygen tambin genera dos archivos esquema XML index.xsd (para el
archivo index) und.xsd (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árr