Documentación automática con Doxygen

Transcripción

1 Documentación automática con Doxygen 4 de abril de 2008 () Documentación automática con Doxygen 4 de abril de / 16

2 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 / 16

3 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 L A T E X RTF Postscript, PDF Unix man pages Windows help compressed HTML XML () Documentación automática con Doxygen 4 de abril de / 16

4 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 $ a p t i t u d e i n s t a l l t e x l i v e # LaTeX $ a p t i t u d e i n s t a l l graphviz # D i b u j a r clases $ a p t i t u d e i n s t a l l doxygen gui # 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 / 16

5 Cómo usar Doxygen 1 Partimos de fichero fuente (o un arbol de ficheros), Posiblemente, documentado «al estilo doxygen» 2 Creamos un fichero de configuración para Doxygen Conjunto de parámetros para generar la documenación 3 Ejecutamos Doxygen y obtenemos el resultado Conjunto de ficheros HTML, L A T E X, 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 / 16

6 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 = <patrones 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 / 16

7 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 / 16

8 Generar salida L A T E X/ PDF / PS El fichero de configuración debe contener: GENERATE_LATEX = YES Para PDF, es recomendable: PDF_HYPERLINKS USE_PDFLATEX = YES = 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 pdf () Documentación automática con Doxygen 4 de abril de / 16

9 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 t a r. bz2 $ t a r x j f octave t a r. bz2 $ doxygen g Editamos el fichero Doxyfile INPUT = octave 3.0.0/ l i b o c t a v e FILE_PATTERNS =. h GENERATE_HTML = YES GENERATE_LATEX = NO EXTRACT_ALL = YES Ejecutamos doxygen y miramos el resultado: html/index.html () Documentación automática con Doxygen 4 de abril de / 16

10 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 / 16

11 Ejemplo 2. Diagramas complejos 1 Utilizar el código que está en tallerdoxygen/ejemplo2 2 Generar documentación: 1 Con HAVE_DOT = NO 2 Con HAVE_DOT = YES 3 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 / 16

12 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 / i n t simple =0; simple 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 Convierte comandos HTML en L A T E X (para salida L A T E X)... () Documentación automática con Doxygen 4 de abril de / 16

13 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 barra 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 / 16

14 Bloques de documentación (C/C++) { Descripción breve Dos tipos de descripción (optativas) Documentación detallada 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 / 16

15 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 / 16

16 Ejemplo 3... / Metrónomo abstracto. Un metrónomo es algo capaz de latir a un determinado ritmo ( expresado en l a t i d o s por minuto ). / class Metronome { public : / Destructor, 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 stop ( ) const = 0; / F i j a r l a bpm velocidad 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 velocidad 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 / 16

17 Ejemplo 3... / Metrónomo abstracto. Un metrónomo es algo capaz de latir a un determinado ritmo ( expresado en l a t i d o s por minuto ). / class Metronome { public : / Destructor, 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 stop ( ) const = 0; / F i j a r l a bpm velocidad 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 velocidad 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 / 16

18 Mucho más que decir... Documentación en otros lenguajes Inclusión de imágenes y fórmulas (sólo L A T E Xy 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 pdf.zip () Documentación automática con Doxygen 4 de abril de / 16