Ya llevo un buen tiempo ocupando esta herramienta (y con ganas de escribir de ella), pero no había tenido tiempo.

Doxygen es un programa esencialmente de consola, que lee el código fuente de un programa, y a partir de los «comentarios» más las definiciones del propio código genera la documentación, la cual puede hacerse en varios formatos a la vez.

Dentro de los formatos de documento que más me interesan está disponible el HTML (varias páginas con enlaces entre sí) y LaTeX (el cual se puede pasar a PDF con pdflatex).

En el proyecto GDT, he estado traspasando la antigua documentación a los comentarios del código fuente.

Lo interesante de Doxygen, es que en sí trabaja parecido a un compilador, en el sentido de que analiza el texto, la sintaxis, reconoce el lenguaje,y además permite su propia sintaxis en los comentarios, de modo que cualquier cosa que uno escriba puede ser formateada al generar el documento, pero sin alterar la funcionalidad del programa.

Otro dato bueno, es que Doxygen permite ocupar una herramienta externa de Graphviz llamada «dot«. Este programita hace gráficos/diagramas. En conjunto con Doxygen, genera los diagramas de colaboración y herencia entre las Clases.

Finalmente, obtenemos un documento que hace referencia a todo nuestro programa, de calidad profesional, y que permite una facil publicación.

El único contra que llevo hasta el minuto, es que en la versión PDF, la documentación de GDT me está quedando un poquito pasada de peso (3 MB, con más de 500 páginas). Tal vez sea porque active la opción que incluye todos los métodos heredados en las Clases hijas, o quizás GDT tiene muchas Clases.

Hay 2 cosas que he descubierto muy bien aún, pero me parece que se pueden hacer son:

• Agrandar el tamaño de las fórmulas matemáticas.
• Incluir imágenes en el PDF (para contribuir con la obesidad del documento :P)

Seguir leyendo Haciendo documentación decente con Doxygen →