Informática I

Herramientas de Documentación
Doxygen

Alejandro Furfaro

Marzo 2011
Introducción Configuración Generando la documentación Preparando el código para su documentación

Temario

1 Introducción
2 Configuración
3 Generando la documentación
4 Preparando el código para su
documentación

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

¿Que es doxygen?

Doxygen es una herramienta para convertir los

comentarios de un programa escrito en C, C++,
VHDL, PHP, C#, y Java (entre otros lenguajes), en
documentación suficientemente prolija y presentable
como para poser publicarse. Maneja la salida de
documentación en formatos: html, LATEX, pdf, rtf, entre
otros. Y lo mas interesante es que la documentación
se genera de manera automática, y a partir de los
archivos fuente de modo que siempre
será consistente con éstos.

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Ventajas de usar Doxygen

1 Al escribir la documentación en el mismo archivo fuente en

forma de comentarios, nos releva de mantener otra
documentación separada de los fuentes.
2 La documentación se genera en forma automática
agregando además diagramas de interacción entre los
diferentes módulos
3 Permite documentar variables, estructuras de datos
además de las funciones.
4 Es una herramienta de documentación automática. Hay
otras pero su uso genera el hábito metodológico de
trabajo.

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Instalación

Hace falta instalar los siguientes paquetes

sudo apt−g e t i n s t a l l doxygen

sudo apt−g e t i n s t a l l g r a p h v i z

Opcionalmente (aunque no estarı́a de mas...)

sudo apt−g e t i n s t a l l k a t e

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Instalación

Hace falta instalar los siguientes paquetes

sudo apt−g e t i n s t a l l doxygen

sudo apt−g e t i n s t a l l g r a p h v i z

Opcionalmente (aunque no estarı́a de mas...)

sudo apt−g e t i n s t a l l k a t e

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

¿Que mas hace falta para comenzar?

1 Escribir comentarios claros, y suficientes para describir

cada función, antes de comenzar a “codearla”.
2 Una vez dentro de ella, insertar comentarios de modo de
describir la operación (al menos los “big steps”)
3 Observar buenas prácticas de programación: Identar
código, Usar convenciones para nombres de variables y
funciones, Escribir código de manera “legible”.
4 Entender al comentario como parte escencial de la
aplicación: Cada agregado o modificación debe ser
documentado describiendo sus caracterı́sticas, fecha y
autor.

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

¿Que mas hace falta para comenzar?

1 Escribir comentarios claros, y suficientes para describir

cada función, antes de comenzar a “codearla”.
2 Una vez dentro de ella, insertar comentarios de modo de
describir la operación (al menos los “big steps”)
3 Observar buenas prácticas de programación: Identar
código, Usar convenciones para nombres de variables y
funciones, Escribir código de manera “legible”.
4 Entender al comentario como parte escencial de la
aplicación: Cada agregado o modificación debe ser
documentado describiendo sus caracterı́sticas, fecha y
autor.

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

¿Que mas hace falta para comenzar?

1 Escribir comentarios claros, y suficientes para describir

cada función, antes de comenzar a “codearla”.
2 Una vez dentro de ella, insertar comentarios de modo de
describir la operación (al menos los “big steps”)
3 Observar buenas prácticas de programación: Identar
código, Usar convenciones para nombres de variables y
funciones, Escribir código de manera “legible”.
4 Entender al comentario como parte escencial de la
aplicación: Cada agregado o modificación debe ser
documentado describiendo sus caracterı́sticas, fecha y
autor.

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

¿Que mas hace falta para comenzar?

1 Escribir comentarios claros, y suficientes para describir

cada función, antes de comenzar a “codearla”.
2 Una vez dentro de ella, insertar comentarios de modo de
describir la operación (al menos los “big steps”)
3 Observar buenas prácticas de programación: Identar
código, Usar convenciones para nombres de variables y
funciones, Escribir código de manera “legible”.
4 Entender al comentario como parte escencial de la
aplicación: Cada agregado o modificación debe ser
documentado describiendo sus caracterı́sticas, fecha y
autor.

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

¿Que mas hace falta para comenzar?

1 Escribir comentarios claros, y suficientes para describir

cada función, antes de comenzar a “codearla”.
2 Una vez dentro de ella, insertar comentarios de modo de
describir la operación (al menos los “big steps”)
3 Observar buenas prácticas de programación: Identar
código, Usar convenciones para nombres de variables y
funciones, Escribir código de manera “legible”.
4 Entender al comentario como parte escencial de la
aplicación: Cada agregado o modificación debe ser
documentado describiendo sus caracterı́sticas, fecha y
autor.

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Proyectos documentados en Doxygen

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Una vez instalado....

....Abrimos una terminal e ingresamos al directorio que

contiene nuestros archivos de trabajo.
En ese directorio generamos el archivo de configuración para
Doxygen.
Tipear:

doxygen −g

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Doxyfile

Es el archivo de configuración de doxygen.

Es un archivo de texto.
Todo lo que comienza con # se toma coo comentario
Cada lı́nea válida tiene el formato
PARAMETRO = VALOR

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Parámetros de interés

Parámetro Descripción / Valor

PROJECT NAME Nombre del Proyecto. Ejemplo: Trabajo Prácti-
co No 4.
PROJECT NUMBER Número o versión del proyecto. Ej: Ejercicio
3.4..
OUTPUT DIRECTORY Es el directorio a partir del cual se generará el
árbol de archivos y subdirectorios (ver opción
siguiente) que componen la documentación.
Generalmente usamos =./doxy, de modo que
se genere dentro del directorio del proyecto.
CREATE SUBDIRS Valor default YES. En este caso crea dos nive-
les de subdirectorios a partir del de documen-
tación para almacenar, los diferentes archivos
que la componen.
OUTPUT LANGUAGE Lenguaje en el que queremos generar la docu-
mentación. Default English.

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Parámetros de interés

Parámetro Descripción / Valor

TAB SIZE Es la cantidad de espacios por los que re-
emplazará cada Tab encontrado en el códi-
go. Default: 8.
OPTIMIZE OUTPUT FOR C Si el proyecto es enteramente escrito en
C conviene activar esta opción para que
Doxygen optimice la salida para este len-
guaje. En tal caso es = YES.
EXTRACT ALL Si está en YES, doxygen agregará a la do-
cumentación todo lo que encuentre (fun-
ciones, variables, etc), aunque no se ha-
yan documentado.
INPUT Es el directorio del proyecto, que se toma
como entrada de información para Doxy-
gen. En caso de poner Doxyfile en el mis-
mo directorio del proyecto (como es nues-
tro caso) colocamos =./

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Parámetros de interés

Parámetro Descripción / Valor

INPUT ENCODING Establece el sistema de codificación de ca-
racteres con el que se generará la docu-
mentación: Si se trabaja en inux coloca-
mos UTF-8, para Windows ISO-8859.
GENERATE LATEX Conviene ponerlo en NO (el default es
YES) si no queremos generar la documen-
tación en LATEX.

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Es la parte mas fácil

Tipear en una consola dentro del directorio del proyecto:

doxygen D o x y f i l e

Luego, simplemente hay que abrir el archivo ./doxy/index.html

con un navegador cualquiera y tenemos lista la documentación.

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Como armar los comentarios

/∗ ∗
∗ E s t i l o JavaDoc : I n i c i a r con ’ / ∗ ∗ ’
Apto para programas en C
Los a s t e r i s c o s i n t e r m e d i o s son o p c i o n a l e s
∗/

/∗ !
∗ E s t i l o QT
Los a s t e r i s c o s i n t e r m e d i o s son o p c i o n a l e s
∗/

// /
/ / E s t i l o C++

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Macros - Documentación general del programa

/∗ ∗
\ f i l e programa . c
\ b r i e f Este a r c h i v o c o n t i e n e e l programa
principal
\ d e t a i l s Aqui nos explayamos sobre l a t a r e a
que r e a i z a r e l programa o l a
funci n
\ a u t h o r A l e j a n d r o F u r f a r o a f u r f a r o @ i e e e . org
\ date 30 de Marzo de 2011
\ version 1.0.0
∗/

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Macros - Documentación general de una función

/∗ ∗
\ fn void p r i n t t i m e (∗ struc tv )
\ b r e f Funcion para o b t e n e r l a fecha y l a hora
con f o r m a t o .
\ d e t a i l s En p r i m e r i n s t a n c i a se l l a m a a g e t t i m e o f d a y ,
pasando como argumento e l p u n t e r o a una
e s t r u c t u r a t i m e v a l ( t v ) . Luego con s t r f t i m e ( )
se l e da un f o r m a t o apto para p r e s e n t a r un
t i m e stamp con e l f o r m a t o
a o −mes−d i a horas : minutos : segundos .
\param [ i n ] ∗ s t r u c t v : p u n t e r o a una
estructura timeval ( tv )
\ r e t u r n Nada ( No r e g r e s a no r e g r e s a v a l o r e s
\ a u t h o r A l e j a n d r o F u r f a r o a f u r f a r o @ i e e e . org
\ date 2011.05.08
\ version 1.0.0
∗/

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Documentando variables

Versión compacta:
unsigned char B u f f e r [ B u f f e r s i z e ] ; / / !< B u f f e r para r e c i b i r c

Versión extendida
/∗ ∗
\ v a r unsigned char B u f f e r [ B u f f e r s i z e ] ;
\ b r i e f B u f f e r para r e c i b i r c a r a c t e r e s
\ d e t a i l s Aqui s i es n e c e s a r i o podemos e x pl a y ar n o s
acerca de l a v a r i a b l e .
∗/
unsigned char B u f f e r [ B u f f e r s i z e ] ;

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Documentando variables

Estructuras
/∗ ∗
\ s t r u c t coordenada
\ b r i e f V a r i a b l e para almacenar un par de coordenadas ( x , y )
\ d e t a i l s Aqui s i es n e c e s a r i o podemos e x pl a y ar n o s
acerca de l a e s t r u c t u r a .
∗/
s t r u c t coordenada {
i n t x ; / / !< Coordenada x ;
i n t y ; / / !< Coordenada y ;
};

Alejandro Furfaro Herramientas de Documentación

Introducción Configuración Generando la documentación Preparando el código para su documentación

Documentando variables

En general
\ struct
\enum
\union
\ class
\ def
\ typedef

Alejandro Furfaro Herramientas de Documentación