Documentacin automtica con Doxygen

4 de abril de 2008

()

Documentacin automtica con Doxygen

4 de abril de 2008

1 / 16

Introduccin

Cmo utilizar Doxygen

Documentacin del cdigo fuente

()

Documentacin automtica con Doxygen

4 de abril de 2008

2 / 16

Qu es Doxygen?
Sistema de documentacin para: C++, C, Java, Objective-C, Python,
IDL, Fortran, VHDL, PHP, C#
Posibilidades:
Extrar la estructura del cdigo fuente de un conjunto de ficheros que
no han sido expresamente preparados para Doxygen
Generar documentacin a partir de un cojunto de ficheros de cdigo
expresamente documentados al estilo Doxygen
Otras.
Formatos de salida soportados:
HTML
LATEX
RTF
Postscript, PDF
Unix man pages
Windows help compressed HTML
XML

http://www.stack.nl/~dimitri/doxygen/
()

Documentacin automtica con Doxygen

4 de abril de 2008

2 / 16

Instalacin

GNU/Linux, lnea de comando (por ejemplo, Debian)


$ a p t i t u d e i n s t a l l doxygen
$ aptitude i n s t a l l texlive
$ a p t i t u d e i n s t a l l graphviz

# LaTeX
# Dibujar clases

$ a p t i t u d e i n s t a l l doxygeng u i # Opcional
$ a p t i t u d e i n s t a l l doxymacs
# Usa e l mejor e d i t o r ; )

GNU/Linux, interfaz grfica (Synaptic, YAST,...)

Windows, Macintosh,...

()

Documentacin automtica con Doxygen

4 de abril de 2008

3 / 16

Cmo usar Doxygen

1

Partimos de fichero fuente (o un arbol de ficheros),

Creamos un fichero de configuracin para Doxygen

Posiblemente, documentado al estilo doxygen

Conjunto de parmetros para generar la documenacin
3

Ejecutamos Doxygen y obtenemos el resultado

Conjunto de ficheros HTML, LATEX, PDF...

Para (2) y (3), dos posibilidades:

(a) O bien usar editor de textos + lnea de comandos
(b) O bien usar una GUI

()

Documentacin automtica con Doxygen

4 de abril de 2008

4 / 16

El fichero de configuracin para Doxygen

Conjunto de sentencias de la forma:

ETIQUETA = VALOR


Cmo generar un fichero patrn:


$ doxygen g


Algunas etiquetas contenidas en el fichero de configuracin:


PROJECT_NAME = <nombre d e l proyecto >
INPUT = < f i c h e r o o d i r e c t o r i o a documentar >
FILE_PATTERNS = < p a t r o n e s de f i c h e r o s a documentar >
GENERATE_HTML = YES
GENERATE_LATEX = YES

EXTRACT_ALL = YES

()

Documentacin automtica con Doxygen


4 de abril de 2008

5 / 16

Generar salida HTML

El fichero de configuracin debe contener:

GENERATE_HTML = YES


Procesamos el cdigo con Doxygen:


$ doxygen


Por defecto, el resultado se encuentra en ./html

Algunas estiquetas tiles (ms en el fichero patrn):

HTML_HEADER =
HTML_FOOTER =
HTML_STYLESHEET =
...

()

Documentacin automtica con Doxygen


4 de abril de 2008

6 / 16

Generar salida LATEX/ PDF / PS

El fichero de configuracin debe contener:

GENERATE_LATEX = YES


Para PDF, es recomendable:


PDF_HYPERLINKS = YES
USE_PDFLATEX
= YES


Procesamos el cdigo con Doxygen:


$ doxygen


Por defecto, el resultado se encuentra en ./latex

Se genera un Makefile que podemos utilizar:

$ cd l a t e x
$ make p d f


()

Documentacin automtica con Doxygen

4 de abril de 2008

7 / 16

Ejemplo 1. Anlisis de la biblioteca C++ de GNU Octave

GNU Octave is a high-level language, primarily intended for numerical computations.

Descargamos el cdigo y preparamos un fichero patrn para doxygen

$
$
$
$

mkdir ejemplo1 ; cd ejemplo1

wget f t p : / / f t p . octave . org / pub / octave / octave 3 . 0 . 0 . t a r . bz2
t a r x j f octave 3 . 0 . 0 . t a r . bz2
doxygen g

Editamos el fichero Doxyfile



INPUT
FILE_PATTERNS
GENERATE_HTML
GENERATE_LATEX
EXTRACT_ALL

=
=
=
=
=

octave 3 . 0 . 0 / l i b o c t a v e
.h
YES
NO
YES

Ejecutamos doxygen y miramos el resultado: html/index.html

()

Documentacin automtica con Doxygen

4 de abril de 2008

8 / 16

Observaciones
Doxygen genera numerosos enlaces de forma automtica:
Listado de ficheros
Listados de clases (alfabtico/jeraquizado) y de miembros
En cada clase:
Enlace al fichero fuente
Enlace a documentacin de cada miembro
...

Por defecto, Doxygen genera automticamente diagramas de herencia

(CLASS_DIAGRAMS = YES)
Si est instalado graphviz (y si HAVE_DOT = YES) , puede generar
diagramas se pueden generar grficos avanzados:
Si GRAPHICAL_HIERARCHY = YES (por defecto), se crea un diagrama

de jerarqua de clases (slo HTML)

Si rCOLLABORATION_GRAPH = YES (por defecto), se crea un diagrama

con herencia+uso entre clases

Etc (CALL_GRAP, CALLER_GRAPH,...)
()

Documentacin automtica con Doxygen

4 de abril de 2008

9 / 16

Ejemplo 2. Diagramas complejos

Utilizar el cdigo que est en tallerDoxygen/ejemplo2

Generar documentacin:
1
2

Con HAVE_DOT = NO
Con HAVE_DOT = YES

En el ejemplo anterior (librera de Octave), se podra haber hecho

HAVE_DOT = YES, pero tarda mucho!

()

Documentacin automtica con Doxygen

4 de abril de 2008

10 / 16

Cmo documentar el cdigo fuente

Cmo documentar un elemento del cdigo?

Delante del elemento a documentar
Bloque de documentacin especial
En otro lugar (menos habitual)
Ejemplo

/

Una v a r i a b l e s i m p l e
/
i n t s i m p l e =0;

Cuando Doxygen parsea los bloques...

Elimina asteriscos (*)

Intepreta lneas en blanco como separadores de prrafos
Crea enlaces entre clases y otros elementos documentados
Ejecuta los comandos especiales que encuentra (@param, @see,..)
Convierte comandos HTML en LATEX (para salida LATEX)
...
()

Documentacin automtica con Doxygen

4 de abril de 2008

11 / 16

Bloques de documentacin (C/C++)

Varios estilos...

/
Comentario a l e s t i l o JavaDoc
/


/ !
Comentario a l e s t i l o Qt
/



// /
/ / / Comentarios C++ con una b a r r a a d i c i o n a l
// /


/ / /
Un comentario muy v i s i b l e
/

()

Documentacin automtica con Doxygen

4 de abril de 2008


12 / 16

Bloques de documentacin (C/C++)


Descripcin breve
Dos tipos de descripcin (optativas)
Documentacin detallada

/ @brief Descripcin breve

La descripcin detallada empieza tras una lnea en blanco

/


(tambin podramos haber usado \brief: estilo Qt).

/ / / Una lnea especial de C++ aislada es documentacin breve

/ / / El resto es descripcin detallada

Si JAVADOC_AUTOBRIEF=YES

/ La descripcin breve termina con un punto, como ste. El resto
es la documentacin detallada, bla, bla, bla...
/


()

Documentacin automtica con Doxygen

4 de abril de 2008

13 / 16

Ejemplo 3. Clases C++ comentadas a la Doxygen

Idea: documentacin de clases representando variantes de un

metrnomo

El cdigo est en tallerDoxygen/ejemplo3

()

Documentacin automtica con Doxygen

4 de abril de 2008

14 / 16

Ejemplo 3...

/

Metrnomo abstracto. Un metrnomo es algo capaz de latir a un

determinado r i t m o ( expresado en l a t i d o s por minuto ) .
/
class Metronome {
public :
/ D e s t r u c t o r , no documentado en Doxygen . /
v i r t u a l ~Metronomo ( ) { }
/ Arrancar el metrnomo. /
v i r t u a l void s t a r t ( ) const = 0 ;
/ Detener el metrnomo. /
v i r t u a l void s t o p ( ) const = 0 ;
/ F i j a r la velocidad .
@param bpm v e l o c i d a d en l a t i d o s ( beats ) por minuto /
v i r t u a l void set_bpm ( unsigned i n t bpm) const =0;
/ Obtener l a v e l o c i d a d .
@return v e l o c i d a d en l a t i d o s ( beats ) por minuto /
v i r t u a l unsigned i n t get_bpm ( ) const = 0 ;

};
()

Documentacin automtica con Doxygen

4 de abril de 2008

15 / 16

Ejemplo 3...

/

Metrnomo abstracto. Un metrnomo es algo capaz de latir a un

determinado r i t m o ( expresado en l a t i d o s por minuto ) .
/
class Metronome {
public :
/ D e s t r u c t o r , no documentado en Doxygen . /
v i r t u a l ~Metronomo ( ) { }
/ Arrancar el metrnomo. /
v i r t u a l void s t a r t ( ) const = 0 ;
/ Detener el metrnomo. /
v i r t u a l void s t o p ( ) const = 0 ;
/ F i j a r la velocidad .
@param bpm v e l o c i d a d en l a t i d o s ( beats ) por minuto /
v i r t u a l void set_bpm ( unsigned i n t bpm) const =0;
/ Obtener l a v e l o c i d a d .
@return v e l o c i d a d en l a t i d o s ( beats ) por minuto /
v i r t u a l unsigned i n t get_bpm ( ) const = 0 ;

};
()

Documentacin automtica con Doxygen

4 de abril de 2008

16 / 16

Mucho ms que decir...

Documentacin en otros lenguajes

Inclusin de imgenes y frmulas (slo LATEXy HTML)
Agrupacin de documentacin en bloques de elementos con
semntica comn
Escritura de documentacin en formato HTML
Etc

ftp://ftp.stack.nl/pub/users/dimitri/doxygen_manual-1.
5.5.pdf.zip

()

Documentacin automtica con Doxygen

4 de abril de 2008

17 / 16