Doxigen
-
Upload
jose-antonio-garcia -
Category
Documents
-
view
11 -
download
5
description
Transcript of 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
() 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)$ 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,...
() Documentacin automtica con Doxygen 4 de abril de 2008 3 / 16
-
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
() 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 = 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 =. . .
() 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 = 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
() 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, 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,...)
() Documentacin automtica con Doxygen 4 de abril de 2008 9 / 16
-
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!
() Documentacin automtica con Doxygen 4 de abril de 2008 10 / 16
-
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) ...
() 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 barra 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++)
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... /
() 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 unmetrnomo
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 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
() Documentacin automtica con Doxygen 4 de abril de 2008 17 / 16
IntroduccinCmo utilizar DoxygenDocumentacin del cdigo fuente