Documentaci on de proyectos con Doxygen

Jos e Tom as Tocino Garc a josetomas.tocino@uca.es

16 de marzo de 2011

Jos e Tom as Tocino Garc a josetomas.tocino@uca.es

Documentaci on de proyectos con Doxygen

Qu e es Doxygen?

Doxygen es una herramienta de generaci on autom atica de documentaci on.

Es capaz de leer el c odigo y documentarlo desde cero o ayudado de una sintaxis especial, muy sencilla, que aprenderemos aqu . Funciona con muchos lenguajes: C, C++, Java, PHP, Python, VHDL... El resultado tambi en puede mostrarse en muchos formatos: en forma de web HTML, como un documento PDF, etc etera.

Jos e Tom as Tocino Garc a josetomas.tocino@uca.es

Documentaci on de proyectos con Doxygen

Elementos que conforman Doxygen

doxygen -g
Generamos el fichero inicial

Archivo de configuracin

Doxyfile

doxygen
Generamos la documentacin

Documentacin generada
Habr un directorio por cada formato en el que hayamos generado la documentacin

*.h, *.cpp
Ficheros de cdigo fuente

Doxygen viene en los repositorios de la mayor a de distribuciones: sudo apt-get install doxygen El chero doxyfile guarda las opciones de conguraci on. Por A defecto se genera en formato HTML y L TEX.
Jos e Tom as Tocino Garc a josetomas.tocino@uca.es Documentaci on de proyectos con Doxygen

Principales opciones del chero de conguraci on

Nombre del proyecto: PROJECT NAME = SecretProject Idioma de la interfaz: OUTPUT LANGUAGE = English (*) Archivos a leer: INPUT = FILE PATTERNS = Extraer todo: EXTRACT ALL = YES Formatos a generar: GENERATE HTML = YES Usar Graphviz para generar los diagramas: HAVE DOT = YES Descripci on breve, termina con un punto: JAVADOC AUTOBRIEF = YES
Jos e Tom as Tocino Garc a josetomas.tocino@uca.es Documentaci on de proyectos con Doxygen

Sintaxis b asica para documentar el c odigo

Los comentarios que Doxygen interpreta como documentaci on tienen una sintaxis especial. Siempre se colocan justo antes del c odigo que queramos documentar. Las sintaxis m as habituales son los comentarios con tres barras:
1

// / Esto es un comentario de Doxygen

O los comentarios en bloque con dos asteriscos de inicio:

1 2 3

/* * * Esto es un comentario de bloque */

Jos e Tom as Tocino Garc a josetomas.tocino@uca.es

Documentaci on de proyectos con Doxygen

Partes de la documentaci on de un elemento

Doxygen divide la documentaci on de los elementos en tres partes:
1

Descripci on corta: en una l nea, explicar brevemente el c odigo. Descripci on larga: p arrafo con varias l neas con una explicaci on m as extensa. Hay que dejar un salto de l nea para indicar el comienzo de la descripci on larga. Si tenemos activado JAVADOC AUTOBRIEF = YES, la descripci on larga comienza tras el primer punto en los comentarios tipo /** ... */ Elementos adicionales: podemos documentar, por ejemplo, para qu e sirve cada par ametro de entrada, o qu e valores devuelve la funci on, etc. Utilizaremos unos comandos del estilo @brief, @param, @return...

Jos e Tom as Tocino Garc a josetomas.tocino@uca.es

Documentaci on de proyectos con Doxygen

Un ejemplo

1 2 3 4 5 6 7 8 9 10 11

// / Representa una ventana . // / Esto es la descripcion detallada class Ventana { public : // / Abre la ventana . // / Las bisagras deben estar bien engrasadas . void Abrir () ; // / Color de la ventana . int color ; };

Jos e Tom as Tocino Garc a josetomas.tocino@uca.es

Documentaci on de proyectos con Doxygen

Un ejemplo
Mismo ejemplo, pero sintaxis alternativa
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

/* * * @brief Representa una ventana . * * Esto es la descripcion detallada . */ class Ventana { public : /* * * @brief Abre la ventana . * * Las bisagras deben estar bien engrasadas . */ void Abrir () ; /* * Color de la ventana */ int color ; };
Jos e Tom as Tocino Garc a josetomas.tocino@uca.es Documentaci on de proyectos con Doxygen

Elementos adicionales
Los elementos adicionales aportan mucha informaci on:
1 2 3 4 5 6 7 8 9 10 11 12 13

/* * * @brief Cierra la ventana . * * Permite indicar la velocidad a la que * cerrar la ventana . * * @param v Velocidad a la que se cierra . * * @return true si la ventana se ha roto * del portazo . * */ bool Cerrar ( float v ) ;

Jos e Tom as Tocino Garc a josetomas.tocino@uca.es

Documentaci on de proyectos con Doxygen

Elementos adicionales
Hay una lista inmensa de comandos que podemos usar adem as de los ya vistos: @author: autor del c odigo. @date: fecha. @exception: posibles excepciones que lanza el m etodo. @todo: elementos pendientes en la lista TO-DO. Podemos agrupar elementos:
1 2 3 4 5

// / @ { // / @name Coordenadas de las ventanas float x ; float y ; // / @ }

Jos e Tom as Tocino Garc a josetomas.tocino@uca.es

Documentaci on de proyectos con Doxygen

Chimp on

Preguntas?

Jos e Tom as Tocino Garc a josetomas.tocino@uca.es

Documentaci on de proyectos con Doxygen