Manuscrito Digital: Doxygen: documentando código

Hace unos dias estaba buscando una herramienta que me ayudara a documentar mi código, comenze de 0, pero no dio buenos resultados, asi que opté por algo que habia visto alguna vez: doxygen.

La idea es simple: hacer la documentación EN el archivo fuente. Esto da una gran ventaja a la hora de evolucionar un programa, mucho más cuando los requerimientos no están del todo claro :P

Puedo decir que doxygen cumple las espectativas, la creación del paquete de documentación en HTML es rapida, sencilla y parece que puede ser muy poderosa (recuerda que solo llevo un par de dias usandolo!).

Los "comandos" para documentar son simples y estéticos, y lo mejor de todo, puedes documentar el código... digamos que por separado, esto es, escribes lo que contendrá el HTML/PDF/etc como si fuese un ente aparte, mientras sigues poniendo comentarios del tipo:


/* Ponemos este contador en lo que se me ocurre algo más */
int cont = 0;

Curioso, no? Veamos algo un poquitín elaborado:


/** @fn int RellenaCirculo (int color, int centro_x, int centro_y, int radio);
    @brief Rellena con el color indicado un círculo trigonométrico.
    @param[in]    color        El color a usar basado la lista de colores
    @param[in]    centro_x     Coordenada del punto centro del círculo en el eje X
    @param[in]    centro_y     Coordenada del punto centro del círculo en el eje Y
    @param[in]    radio        Radio geométrico para representar el circulo
    @return        verdadero en caso de exito, falso si hubo error.
    @todo Hacer la función!!!
    @author Antonio
*/

Se ve muy bien para ser la primera impresión... amor a primera vista? Uno nunca sabe :)

Enlaces de interés: