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 
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:
- Página de un maestro costarricense, muy interesante
- “Uso de Doxygen para especificar módulos y programas”
- http://www.di-mare.com/adolfo/p/Doxygen.htm
- Página principal del proyecto
- El manual mas nuevo (al momento de escribir la nota)
