Presentación

Documentación automática con Doxygen
4 de abril de 2008
()
Documentación automática con Doxygen
4 de abril de 2008
1 / 16
1
Introducción
2
Cómo utilizar Doxygen
3
Documentación del código fuente
()
Documentación automática con Doxygen
4 de abril de 2008
2 / 16
¿Qué es Doxygen?
• Sistema de documentación para: C++, C, Java, Objective-C, Python,
IDL, Fortran, VHDL, PHP, C#
• Posibilidades:
• Extrar la estructura del código fuente de un conjunto de ficheros que
no han sido expresamente preparados para Doxygen
• Generar documentación a partir de un cojunto de ficheros de código
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/
()
Documentación automática con Doxygen
4 de abril de 2008
2 / 16
Instalación
• GNU/Linux, línea 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 doxygen−g 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 gráfica (Synaptic, YAST,...)
• Windows, Macintosh,...
()
Documentación automática con Doxygen
4 de abril de 2008
3 / 16
Cómo usar Doxygen
1
Partimos de fichero fuente (o un arbol de ficheros),
2
Creamos un fichero de configuración para Doxygen
• Posiblemente, documentado «al estilo doxygen»
• Conjunto de parámetros para generar la documenación
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 + línea de comandos
(b) O bien usar una GUI
()
Documentación automática con Doxygen
4 de abril de 2008
4 / 16
El fichero de configuración para Doxygen
Conjunto de sentencias de la forma:
ETIQUETA = VALOR
Cómo generar un fichero patrón:
$ doxygen −g
Algunas etiquetas contenidas en el fichero de configuración:
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
()
Documentación automática con Doxygen
4 de abril de 2008
5 / 16
Generar salida HTML
• El fichero de configuración debe contener:
GENERATE_HTML = YES
• Procesamos el código con Doxygen:
$ doxygen
• Por defecto, el resultado se encuentra en ./html
• Algunas estiquetas útiles (más en el fichero patrón):
HTML_HEADER =
HTML_FOOTER =
HTML_STYLESHEET =
...
()
Documentación automática con Doxygen
4 de abril de 2008
6 / 16
Generar salida LATEX/ PDF / PS
• El fichero de configuración debe contener:
GENERATE_LATEX = YES
• Para PDF, es recomendable:
PDF_HYPERLINKS = YES
USE_PDFLATEX
= YES
• Procesamos el código 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
()
Documentación automática con Doxygen
4 de abril de 2008
7 / 16
Ejemplo 1. Análisis de la biblioteca C++ de GNU Octave
• GNU Octave is a high-level language, primarily intended for numerical computations.
• Descargamos el código y preparamos un fichero patrón 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
()
Documentación automática con Doxygen
4 de abril de 2008
8 / 16
Observaciones
• Doxygen genera numerosos enlaces de forma automática:
• Listado de ficheros
• Listados de clases (alfabético/jeraquizado) y de miembros
• En cada clase:
• Enlace al fichero fuente
• Enlace a documentación de cada miembro
• ...
• Por defecto, Doxygen genera automáticamente diagramas de herencia
(CLASS_DIAGRAMS = YES)
• Si está instalado graphviz (y si HAVE_DOT = YES) , puede generar
diagramas se pueden generar gráficos avanzados:
• Si GRAPHICAL_HIERARCHY = YES (por defecto), se crea un diagrama
de jerarquía de clases (sólo HTML)
• Si rCOLLABORATION_GRAPH = YES (por defecto), se crea un diagrama
con herencia+uso entre clases
• Etc (CALL_GRAP, CALLER_GRAPH,...)
()
Documentación automática con Doxygen
4 de abril de 2008
9 / 16
Ejemplo 2. Diagramas complejos
1
Utilizar el código que está en tallerDoxygen/ejemplo2
2
Generar documentación:
1
2
3
Con HAVE_DOT = NO
Con HAVE_DOT = YES
En el ejemplo anterior (librería de Octave), se podría haber hecho
HAVE_DOT = YES, pero tarda mucho!
()
Documentación automática con Doxygen
4 de abril de 2008
10 / 16
Cómo documentar el código fuente
• ¿Cómo documentar un elemento del código?
Delante del elemento a documentar
Bloque de documentación 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 líneas en blanco como separadores de párrafos
Crea enlaces entre clases y otros elementos documentados
Ejecuta los comandos especiales que encuentra (@param, @see,..)
Convierte comandos HTML en LATEX (para salida LATEX)
...
()
Documentación automática con Doxygen
4 de abril de 2008
11 / 16
Bloques de documentación (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
∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗∗ ∗ /
()
Documentación automática con Doxygen
4 de abril de 2008
12 / 16
Bloques de documentación (C/C++)
Descripción breve
• Dos tipos de descripción (optativas)
Documentación detallada
•
/ ∗ ∗ @brief Descripción breve
∗
∗ La descripción detallada empieza tras una línea en blanco
∗/
(también podríamos haber usado \brief: estilo Qt).
•
/ / / Una línea especial de C++ aislada es documentación breve
/ / / El resto es descripción detallada
• Si JAVADOC_AUTOBRIEF=YES
/ ∗ ∗ La descripción breve termina con un punto, como éste. El resto
∗ es la documentación detallada, bla, bla, bla...
∗/
()
Documentación automática con Doxygen
4 de abril de 2008
13 / 16
Ejemplo 3. Clases C++ comentadas “a la Doxygen”
• Idea: documentación de clases representando variantes de un
metrónomo
• El código está en tallerDoxygen/ejemplo3
()
Documentación automática con Doxygen
4 de abril de 2008
14 / 16
Ejemplo 3...
/∗∗
∗ Metrónomo abstracto. Un metrónomo 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 metrónomo. ∗ /
v i r t u a l void s t a r t ( ) const = 0 ;
/ ∗ ∗ Detener el metrónomo. ∗ /
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 ;
};
()
Documentación automática con Doxygen
4 de abril de 2008
15 / 16
Ejemplo 3...
/∗∗
∗ Metrónomo abstracto. Un metrónomo 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 metrónomo. ∗ /
v i r t u a l void s t a r t ( ) const = 0 ;
/ ∗ ∗ Detener el metrónomo. ∗ /
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 ;
};
()
Documentación automática con Doxygen
4 de abril de 2008
16 / 16
Mucho más que decir...
• Documentación en otros lenguajes
• Inclusión de imágenes y fórmulas (sólo LATEXy HTML)
• Agrupación de documentación en bloques de elementos con
semántica común
• Escritura de documentación en formato HTML
• Etc
ftp://ftp.stack.nl/pub/users/dimitri/doxygen_manual-1.
5.5.pdf.zip
()
Documentación automática con Doxygen
4 de abril de 2008
17 / 16