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)
Para instalar en ubuntu:
sudo apt-get install doxygen graphviz tetex-base tetex-extra
Más información en la web oficial de Doxygen.
La obtencion de los diagramas de colaboración y herencia, debe hacerse a priori, en la fase de diseño del software y no a posteriori a partir de la implementacion.
Esto anula la utilidad de dichos diagramas, salvo que siguen pareciendo muy bonitos en una documentación tecnica.
Es mas, hacer esto deja ver a los ojos de un ingeniero los fallos de diseño (que no implementacion) existentes de forma mucho mas evidente. Fallos que deberian haber sido subsanados siguiendo los ciclos de vida de desarrollo software tradicionales.
Es como obtener los planos de una casa a partir de tenerla ya construida.
En fin… «Cosas veredes Sancho»
2 Cosas:
1) Hacer la documentación DESPUES no quita el deber de planificar ANTES, ya sea con diagramas o con la herramienta que sea. Tampoco digamos que es fácil escribir la documentación a mano e incorporar todo lo anterior en el documento final. Doxygen esta diseñado para esa tarea.
2) Cuando se debe regularizar algún trámite con una propiedad, y los planos están perdidos o en mal estado, se suelen mandar a rehacer. En este caso yo me incorporé tardíamente al proyecto GDT, no soy su fundador, por lo tanto si tiene algún problema de diseño, ya lo tiene, ahora lo que se debe hacer es ver como arreglarlo.
—
Además, debo resaltar que no siempre es necesario un documento con las información sobre como está programada la solución. En el caso de GDT, documentar la API es fundamental, ya que es una librería, y los usuarios a los que está destinada son programadores.
Cómo hacer para que el Doxygen muestre bien los ecentos?
Gracias
Perdón, ‘acentos’
yolo que hice fue escribir los comentarios con codificación html, osea:
á = & a a c u t e ; (todo junto)
é = & e a c u t e ;
…
ñ = & n t i l d e ;
No se si funciona en todos los formatos, pero al menos en html sí.
Lo otro es que te fijes que la codificación de tus archivos fuente sea la misma que utilizará Doxygen, pero en el caso del html, prefiero la primera.
Solucionado!
Cambiar la codificación de la fuente de entrada y salida a LATIN1 y acepta todos los signos de puntuación, incluidos acentos y diéresis.
Saludos
Que onda!!
Oie no tendras un tutorial acerca de doxygen?? que me puedas facilitar…
Saludos
Se que tuve un tutorial, pero lo he estado buscando y no lo encuentro por ningún lado. Pero lo pillé de internet
Lo siento, saludos
Mira estas urls:
http://www.iglues.org/igluesold/manuales/doxmanual/html/
http://www.vjuegos.org/Tutoriales/ManualDoxygen/ManualDoxygen.pdf
http://www.escomposlinux.org/lfs-es/blfs-es-SVN/general/doxygen.html
Espero que te sirvan, un saludo
Hola, gracias por los links. Estoy documentando un proyecto y al incluir imágenes de DOT me las crea en negro. Es posible cambiar el color? Un saludo.