Lo que hace Doxygen es leer el código fuente, analizarlo y extraer información. Parte de la información se toma del significado del código haciendo un análisis similar al que hace un compilador (qué clases hay, qué métodos y atributos tienen, dónde están definidas, etc, etc, etc). Pero además (y esto es lo importante), Doxygen analiza los comentarios, determina cerca de qué declaraciones o definiciones están, y los asocia. Por ejemplo, un comentario antes de una función aparecerá en la documentación asociada a dicha función. Y además, a través de unas pocas palabras claves le podemos dar información adicional para que sepa qué parte del comentario es la descripción resumida, qué parte la descripción larga, dónde nos referimos a argumentos de la función, donde al valor de retorno, qué otros símbolos mencionamos, que tareas pendientes hay asociadas, etc.
Veamos un ejemplo:
Código con comentarios para Doxygen
No todos los comentarios son para que Doxygen los utilice, solo los que le marquemos. Hay más de una forma de marcarlos, pero lo usual introducirlos con /// en lugar de // (o con /** y **/ en lugar de /* y */). En ZinjaI, si no cambiaron los colores por defecto, verán que al introducir el segundo * o la tercer / los comentarios pasan de gris a azul claro. Los grises son los regulares, los azules los de Doxygen. Además de eso, las palabras claves especiales que usamos para darle más pistas se introducen con @, y se muestran en un azul algo más claro si son correctas, o en rojo si no lo son. Si al ingresar la arroba dentro de un comentario Doxygen no ven el menú de autocompletado con los tags posibles, deben activar el índice de Doxygen desde la ventana de Preferencias (menú Archivo -> Preferencias... -> Asistencias -> Autocompletado -> Índices... -> Documentación_Doxygen). En el ejemplo, uso el tag brief para diferenciar la descripción breve (de una línea, que irá en los índices) de la completa, param para los parámetros de funciones, retval para los posibles valores de retorno (podría haber utilizado return y una sola descripción para todos los valores), y todo para tareas pendientes. Creo que estos son en general los más usados.
Resúmen y descripción de la clase generado como HTML. Hasta genera
un diagrama de clases con la relación de herencia detectada en el código.
La documentación puede generarse en varios formatos, pero lo más común es generarla como HTML. Es decir, como páginas web, que permiten enlazar contenido mediante hipervínculos, dar formato con CSS, hacer búsquedas o cambiar vistas con HTML5 y/o JavaScript, etc. Todo se configura desde un archivito llamado "Doxyfile". ZinjaI puede generarlo automáticamente para ustedes, configurando las opciones más comunes desde un cuadro de diálogo especial, para luego actualizar o abrir la documentación cuando quieran con un solo click. Se accede a todo desde el submenú "Generar Documentación" del menú "Herraminetas" (y como todo lo que está en un menú se puede poner en la barra de herramientas o asociar a un atajo de teclado).
Documentación generada para una función miembro de la clase
En ZinjaI, supongo que saben que tienen una funcionalidad para obtener información de una clase, macro, variable global o función, que consiste en colocar el cursor de texto sobre la misma y presionar Shift+F1. Con esto despliegan el panel de ayuda rápida, donde se muestra la información que el parseo del código fuente permite obtener sobre dicho símbolo. Es útil, por ejemplo, para ver su definición completa, para ir a los lugares en el código en donde se declaró y/o definió, o para acceder rápidamente a símbolos relacionados. Si generan la documentación en formato HTML con Doxygen desde ZinjaI, ZinjaI pedirá a Doxygen que genera además un xml adicional donde indica en qué archivo html guardó la documentación de cada símbolo, y podrá luego agregar esta documentación al panel de ayuda rápida (no funciona para cualquier tipo de símbolo, pero sí para funciones por ejemplo).
ZinjaI puede integrar en su panel de ayuda rápida la documentación generada por Doxygen
En resumen, la documentación queda muy bien presentada, es muy fácil de navegar (vean la última captura), y requiere "poco" esfuerzo extra de nuestra parte. Digo "poco" entre comillas porque si estamos acostumbrados a documentar bien nuestras interfaces, entonces todo lo que tenemos que agregar para utilizar Doxygen son una pocas palabras claves a modo de tags. El problema suele ser que no estamos acostumbrados a dedicarle mucho esfuerzo a la documentación interna, y en ese caso comenzar a usar Doxygen sí requiere un esfuerzo adicional considerable. Pero por otro lado, lo bueno es que nos obliga a hacerlo, nos ayuda a crear el hábito, y nos motiva generando algo útil a cambio. En mi caso, el hecho de utilizarlo realmente fue cambiando de a poco mis hábitos relacionados a la documentación interna para mejor. Estoy leeejos de dedicarle todo el tiempo que requiere, pero si comparan partes del código de ZinjaI o PSeInt recientes con partes de hace algunos años notarán la diferencia.
Varias formas de navegar por la documentación generada como HTML. Arriba tiene
botones para ir derecho la lista de clases o archivos, a la izquierda un árbol temático
para recorrer, y en la esquina superior derecha un buscador por palabras claves.
botones para ir derecho la lista de clases o archivos, a la izquierda un árbol temático
para recorrer, y en la esquina superior derecha un buscador por palabras claves.
No hay comentarios:
Publicar un comentario