Documentando con doxygen I

Ahora que he tenido tiempo para trabajar en mis proyectos, me vi en la necesidad de documentar el código (nunca se sabe si alguien quiere aportar) y decidí empezar a usar doxygen.

¿Qué es?

Doxygen es un sistema generador de documentación multiplataforma que puede ser usado para diversos lenguajes como C/C++, D, Objective-C, Python, IDL, Fortran, VHDL, PHP y C#. Su versión estable al escribir este post es la 1.5.9.

Una ventaja es que viene incluido en una gran cantidad de distribuciones de linux por lo que podemos usarlo de inmediato.

¿Cómo funciona?

Básicamente lo que hace el programa es buscar en los archivos fuente de un directorio que especifiquemos cierto código el cual le dice qué y cómo documentar. El resultado final puede ser un documento html navegable, un documento pdf (usando LaTeX), un documento RTF o uno de tipo XML.

Sin embargo antes de lograr lo anterior, se debe generar un archivo de configuración que le diga donde debe buscar los archivos y muchas cosas más. La forma más fácil de crearlo es usando doxywizard, para esto sólo abrimos una consola (o ejecutar comando) y ponemos

doxywizard

Cosa que nos presentará una ventana así:

Para iniciar la configuración podemos usar dos métodos wizard que es básico y servirá para la mayoría de los propósitos y expert que como es de esperar trae muchas más opciones de configuración.

Dentro de wizard encontramos:

Donde podremos elegir el directorio donde guardar el resultado y de donde leer los archivos fuente (si queremos que busque recursivamente también), el formato de la documentación (mencionados anteriormente) y si queremos optimizar el resultado para cierto lenguaje.
Esto es suficiente para poder comenzar a trabajar, se generará el archivo de configuración que podemos guardar donde estimemos conveniente y finalmente hacemos click en start y el proceso comenzará.

En modo experto encontramos disponibles muchas más opciones:

Entre lo que podemos modificar acá encontramos

• Codificación del texto (UTF-8
• Si queremos crear subdirectorios (hasta 4096) para ordenar los archivos generados (que pueden ser muchos dependiendo del tamaño del proyecto)
• Idioma de los distintos menús de los documentos resultantes
• Muchas opciones de "extracción" (build tab), esto es si doxygen debe tomar en cuenta ciertas partes o no a pesar que se encuentren con código de reconocimiento, por ejemplo variables privadas en una clase no serán documentadas de manera predeterminada pero ese comportamiento puede ser cambiado aquí.
• Si deben generarse ciertas secciónes como una lista TODO, o una lista de bugs (build tab)
• Generación de índice alfabético
• Modificar la forma en que se crean la documentación agregando por ejemplo header y/o footer personalizados(HTML), paquetes extra (LaTex), etc
• Si se deben procesar las directivas de preprocesador
• Incluir un motor de búsqueda en el documento html (requiere un servidor php)

Lo bueno es que las opciones que encontrarán contarán con un popup de ayuda, sólo pasen el mouse sobre la parte en que tengan duda y saldrá un recuadro amarillo diciendo para que sirve
Al igual que con el wizard guardamos la configuración y ya estamos listos para empezar (creo que debí haber dejado este paso para el último pero bueno)

Luego les diré que deben incluir para poder generar una documentación para su código

Programación Documentación Doxygen