Doxigen

Documentacin automtica con Doxygen

4 de abril de 2008

() Documentacin automtica con Doxygen 4 de abril de 2008 1 / 16

1 Introduccin

2 Cmo utilizar Doxygen

3 Documentacin del cdigo fuente


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/


Instalacin

GNU/Linux, lnea de comando (por ejemplo, Debian)$ ap t i t ude i n s t a l l doxygen

$ ap t i t ude i n s t a l l t ex l i ve # LaTeX$ ap t i t ude i n s t a l l graphviz # Dibu ja r c lases

$ ap t i t ude i n s t a l l doxygengui # Opcional$ ap t i t ude 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,...


Cmo usar Doxygen

1 Partimos de fichero fuente (o un arbol de ficheros), Posiblemente, documentado al estilo doxygen

2 Creamos un fichero de configuracin para 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


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 = INPUT = < f i c h e r o o d i r e c t o r i o a documentar>FILE_PATTERNS =

GENERATE_HTML = YESGENERATE_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 =. . .


Generar salida LATEX/ PDF / PS

El fichero de configuracin debe contener:GENERATE_LATEX = YES

Para PDF, es recomendable:PDF_HYPERLINKS = YESUSE_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 pdf


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

GNU Octave is a high-level language, prima-rily 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 DoxyfileINPUT = octave 3.0.0/ l i b o c t a v eFILE_PATTERNS = . hGENERATE_HTML = YESGENERATE_LATEX = NOEXTRACT_ALL = 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 generardiagramas se pueden generar grficos avanzados:

Si GRAPHICAL_HIERARCHY = YES (por defecto), se crea un diagramade jerarqua de clases (slo HTML)

Si rCOLLABORATION_GRAPH = YES (por defecto), se crea un diagramacon herencia+uso entre clases

Etc (CALL_GRAP, CALLER_GRAPH,...)


Ejemplo 2. Diagramas complejos

1 Utilizar el cdigo que est en tallerDoxygen/ejemplo2

2 Generar documentacin:

1 Con HAVE_DOT = NO2 Con HAVE_DOT = YES

3 En el ejemplo anterior (librera de Octave), se podra haber hechoHAVE_DOT = YES, pero tarda mucho!


Cmo documentar el cdigo fuente

Cmo documentar un elemento del cdigo?Bloque de documentacin especial

{Delante del elemento a documentarEn otro lugar (menos habitual)

Ejemplo/ Una v a r i a b l e simple /

i n t simple =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) ...


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 barra a d i c i o n a l/ / / / / / Un comentario muy v i s i b l e /


Bloques de documentacin (C/C++)

Dos tipos de descripcin (optativas){

Descripcin breveDocumentacin 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... /


Ejemplo 3. Clases C++ comentadas a la Doxygen

Idea: documentacin de clases representando variantes de unmetrnomo

El cdigo est en tallerDoxygen/ejemplo3


Ejemplo 3.../ Metrnomo abstracto. Un metrnomo es algo capaz de latir a un determinado r i tmo ( expresado en l a t i d o s por minuto ) . /class Metronome {

public :

/ Dest ruc tor , 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 stop ( ) const = 0;

/ F i j a r l a ve loc idad . @param bpm veloc idad 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 ve loc idad . @return ve loc idad 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 tmo ( expresado en l a t i d o s por minuto ) . /class Metronome {

public :

/ Dest ruc tor , 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 stop ( ) const = 0;

/ F i j a r l a ve loc idad . @param bpm veloc idad 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 ve loc idad . @return ve loc idad 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


IntroduccinCmo utilizar DoxygenDocumentacin del cdigo fuente

Doxigen

Documents

Transcript of Doxigen