Doxygen. Marzo 2010 Mat. Renato Leriche Vázquez 1

Tamaño: px

Comenzar la demostración a partir de la página:

Download "Doxygen. Marzo 2010 Mat. Renato Leriche Vázquez 1"

Montserrat Villalobos Franco
hace 8 años
Vistas:

1 Doxygen Marzo 2010 Mat. Renato Leriche Vázquez 1

2 Qué es Doxygen? Es un sistema de documentación código, es decir, un conjunto de herramientas de software para generar documentos en los que se detalla y explican las funcionalidades de los componentes de un software particular. Marzo 2010 Mat. Renato Leriche Vázquez 2

3 Para qué se requiere un sistema de documentación de código? Facilita y automatiza la generación de documentación de software. Facilita la colaboración entre los desarrolladores de un mismo proyecto, ya sean contemporáneos o no. Facilita la comprensión y, por lo tanto, el uso del software (código) por un usuario externo. Marzo 2010 Mat. Renato Leriche Vázquez 3

Facilita la colaboración entre los desarrolladores de un mismo proyecto, ya sean

4 Por qué Doxygen? Free/Open source. Independiente de plataforma. Documenta C/C++, Fortran, Java, Python, etc. Genera documentos en formato HTML, LaTeX, rtf, man, etc. Ampliamente utilizado, creado en Genera la documentación directamente del código. Marzo 2010 Mat. Renato Leriche Vázquez 4

Genera documentos en formato HTML, LaTeX, rtf, man, etc.

5 Funcionamiento básico Archivo de config. Código con doc. doxygen Archivo de doc. Marzo 2010 Mat. Renato Leriche Vázquez 5

6 Creando un archivo de configuración Para generar el archivo de configuración por omisión Doxyfile: > doxygen -g O se puede asignar un nombre al archivo: > doxygen -g archivo_de_configuración Marzo 2010 Mat. Renato Leriche Vázquez 6

-g O se puede asignar un nombre al archivo: > doxygen -g

7 Generando la documentación Para generar la documentación, simplemente se ejecuta: > doxygen si existe el archivo Doxyfile, o > doxygen archivo_de_configuracion usando un archivo de configuración particular. Marzo 2010 Mat. Renato Leriche Vázquez 7

Doxyfile, o > doxygen archivo_de_configuracion usando un

8 Documentación generada Por omisión, se generan dos archivos, de formatos HTML y LaTeX respectivamente, que contienen la (misma) documentación:./html/index.html./latex/refman.tex Nota: En versiones de Doxygen anteriores a 1.6 los archivos de salida por omisión pueden ser de otros formatos. Marzo 2010 Mat. Renato Leriche Vázquez 8

tex Nota: En versiones de Doxygen anteriores a 1.

9 El archivo de configuración Archivo de texto similar al Makefile (case sensitive, los comentarios comienzan con #, expansión de variable de ambiente con $(...)). Consiste en una lista de tags seguidas del símbolo = (o en algunos casos +=) y un valor. Para usar el valor por omisión se omite el valor. Los valores están dados en cadenas de caracteres, usando en caso de cadenas con espacios y usando \ como fin de línea (si se requieren múltiples líneas). Marzo 2010 Mat. Renato Leriche Vázquez 9

Consiste en una lista de tags seguidas del símbolo = (o en algunos casos +=) y un valor.

10 Configurando Doxygen (Project) PROJECT_NAME Ej.: ProjectX, Mi Proyecto OUTPUT_DIRECTORY Ej.: dir,./dir/,../dir CREATE_SUBDIRS crea un sistema de subdirectorios por cada formato de salida. Útil para proyectos grandes. Opciones: YES, NO BRIEF_MEMBER_DESC crea una descripción breve para cada elemento. Opciones: YES, NO TAB_SIZE establece el tamaño del tabulador en los fragmentos de código. Marzo 2010 Mat. Renato Leriche Vázquez 10

11 Configurando Doxygen (Input) INPUT directorios o archivos de entrada. Ej.: /home/usr/proj/src,../../dir1../../dir2, prog.h FILE_PATTERNS Ej.: *.h, *.hpp *.cpp, *.java RECURSIVE para indicar búsqueda recursiva en el directorio de entrada. Opciones: YES, NO EXCLUDE directorios o archivos a excluir. Marzo 2010 Mat. Renato Leriche Vázquez 11

cpp, *.java RECURSIVE para indicar búsqueda recursiva en el directorio de entrada.

12 Configurando Doxygen (Build) EXTRACT_ALL genera documentación incluso para elementos no documentados. YES, NO. SHOW_INCLUDE_FILES muestra la lista de archivos de inclusión en un archivo. YES, NO SHOW_USED_FILES muestra los archivos utilizados en la documentación de un elemento. SORT_MEMBERS_DOCS ordena los elementos alfabéticamente. YES, NO GENERATE_TODO_LIST opciones YES, NO Marzo 2010 Mat. Renato Leriche Vázquez 12

YES, NO SHOW_USED_FILES muestra los archivos utilizados en la documentación de un elemento.

13 Configurando Doxygen (Source) SOURCE_BROWSER genera la lista de archivos fuente utilizados. Opciones YES, NO INLINE_SOURCES incluye el cuerpo de funciones, clases, etc, en la documentación. ALPHABETICAL_INDEX crea el índice en orden alfabético de los elementos en la documentación. COLS_IN_ALPH_INDEX número de columnas en el índice de elementos. Marzo 2010 Mat. Renato Leriche Vázquez 13

ALPHABETICAL_INDEX crea el índice en orden alfabético de los elementos en la documentación.

14 Configurando Doxygen (Output) GENERATE_HTML Opciones: YES, NO HTML_OUTPUT directorio para la documentación HTML, relativo al global si es el caso. GENERATE_LATEX Opciones: YES, NO USE_PDFLATEX utiliza pdflatex para generar el archivo PDF a partir del archivo LaTeX. PDF_HYPERLINKS genera PDF con ligas en lugar de referencias a páginas. Marzo 2010 Mat. Renato Leriche Vázquez 14

GENERATE_LATEX Opciones: YES, NO USE_PDFLATEX utiliza pdflatex para generar el archivo PDF a

15 Configurando Doxygen (Dot) HAVE_DOT indica si está instalada la herramienta dot de Graphviz para crear diagramas. CLASS_DIAGRAMS genera diagramas de clases con superclases. CLASS_GRAPH genera diagramas de clases con todas sus relaciones de herencia. COLLABORATION_GRAPH genera diagramas de toda relación entre elementos. UML_LOOK genera diagramas con estilo UML Marzo 2010 Mat. Renato Leriche Vázquez 15

CLASS_GRAPH genera diagramas de clases con todas sus relaciones de herencia.

16 Documentación de código Los elementos que se pueden documentar son las funciones, clases, miembros de clases (atributos y métodos), enumeraciones, etc. Los bloques de documentación se indican con bloques de comentarios con marcas especiales antes (o en casos después) del elemento. Cada bloque para un elemento puede contener una descripción breve y/o una detallada. Para generar la documentación deseada, se utilizan comandos dentro de los bloques. Marzo 2010 Mat. Renato Leriche Vázquez 16

Los bloques de documentación se indican con bloques de comentarios con marcas especiales antes (o en casos después) del

17 Bloques de documentación /** *...Información... */ /*! *...Información... */ /**...Información... */ /******************* *...Información... *******************/ /// ///...Información... //! //!...Información... //! ///////////////////// /// ///...Información... /// ///////////////////// Marzo 2010 Mat. Renato Leriche Vázquez 17

18 Breve y/o detallada... /*! \brief Breve. * Breve. * * Detallada. */ /** Breve. Detallada. Detallada. Usando JAVADOC_AUTOBRIEF */ /// Breve. /** Detallada. */ //! Breve //! Breve. /*! Detallada. */ /// Breve. Detallada. /// Detallada. Usando /// JAVADOC_AUTOBRIEF Marzo 2010 Mat. Renato Leriche Vázquez 18

/** Detallada. */ //! Breve //! Breve. /*! Detallada. */ /// Breve.

19 Documentando después... Sólo para atributos y parámetros: int num; /*!< Detallada. */ int num; /**< Detallada. */ int num; ///< Detallada. ///< int num; ///< Breve. float funcion( float f /**< Detallada. */ ); Marzo 2010 Mat. Renato Leriche Vázquez 19

20 Comandos para documentación Los comandos de Doxygen comienzan con un backslash \, También se puede utilizar en lugar de \. El estilo de estos comandos es similar al de los de LaTeX. De hecho, existen varios comandos análogos a los de LaTeX que se utilizan para obtener (casi) los mismos resultados. En algunos casos, se pueden utilizar comandos estilo HTML: <comando>... <\comando> Marzo 2010 Mat. Renato Leriche Vázquez 20

$resultados. En algunos casos, se pueden utilizar comandos estilo HTML: <comando>... <\comando> Marzo 2010 Mat.$

21 Comandos para funciones \param para describir un parámetro. \return para describir la salida de una función. Ejemplo: /** Da un elemento. \param i i-ésima columna. \param j j-ésimo renglón. \return El elemento i,j. */ double getelement(int i, int j) const; Marzo 2010 Mat. Renato Leriche Vázquez 21

22 Comandos útiles \brief para descripción breve del elemento. \author para indicar los autores del elemento. \todo para indicar el trabajo por hacer en el elemento. \bug para describir los bugs del elemento. \warning para indicar una advertencia. \see o \sa para hacer referencias a otros elementos. Marzo 2010 Mat. Renato Leriche Vázquez 22

23 Comandos para formato \a palabra tipografía especial. \b palabra, palabras bold, negritas. \c palabra, \code palabras \endcode o <tt>palabras</tt> código, typewriter. \e palabra o \em palabra, palabras enfatizar, itálica. \n o fuerza nueva línea. Marzo 2010 Mat. Renato Leriche Vázquez 23

24 Comandos para fórmulas Se pueden incluir fórmulas en formato LaTeX en el texto de la documentación: \f$ línea de fórmula \f$ entre texto. \f[ líneas de fórmula \f] en párrafo aparte. \f{ambiente_latex}{ líneas de fórmula \f} Ejemplo: /** Usando \f$u_t\f$ en \f$r^2\f$: \f[ F(x,y) = \int_{0}^{\alpha(s)} u_t(x,y) dt \f] */ Marzo 2010 Mat. Renato Leriche Vázquez 24

25 Comandos para páginas También se pueden crear páginas no relacionadas directamente con el código, de manera que sus bloques de documentación no requieren estar antes o después de los elementos. \mainpage título página principal. \page nombre página independiente. \section nombre título sección en una página. \subsection nombre título subsección en una sección. Marzo 2010 Mat. Renato Leriche Vázquez 25

26 Más opciones de doxygen Con -u se actualiza un archivo de configuración de Doxygen. Para generar plantillas para formatos: -w rtf style_sheet -w html header footer style_sheet -w latex header style_sheet Con -s no se generan los comentarios al generar o actualizar un archivo de configuración. Ejemplo: > doxygen -u -s -w html h.html f.html s.css X Marzo 2010 Mat. Renato Leriche Vázquez 26

27 Más información... Marzo 2010 Mat. Renato Leriche Vázquez 27

Documentos relacionados

Documentación automática con Doxygen

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