Doxygen

Doxygen es un sistema para documentar código. Es sencillo y funciona bien.

Los pasos a seguir:

  1. Escribir comentarios en el código con cierto formato.
  2. Se corre Doxygen (previamente instalado) y se revisa la documentación generada.

¡Y ya!

Comentar código

Aunque Doxygen soporta varios lenguajes, me voy a enfocar en C/C++.

Primero, los bloques de comentarios multi-línea relevantes para Doxygen deben comenzarse con /** (con dos asteriscos) o con /*!; hay otros inicios de bloque; pero yo no los uso (búsquenlos si les acomoda otro estilo). En el caso de comentarios de una línea, debe escribirse /// (tres diagonales; en lugar de sólo dos). Si se empieza el comentario con ///<, quiere decir que el comentario corresponde al bloque anterior.

La primera línea del comentario se considera la descripción breve (\brief). Las subsecuentes, a menos de que se indique lo contrario, son descripción larga. Algunos ejemplos:

Un typedef corto:

typedef short Word16; ///< Palabra de 16-bits con signo.

Otro typedef más extenso:

/// Pseudo-fraccional de 32-bits.
/** Es similar al tipo Frac16, pero de 32 bits.
* @see Frac16 */
typedef long Frac32;

Un define:

/// Regresa el valor máximo.
#define MAX(A,B)            ((A>B)?(A):(B))

Un encabezado de archivo:

/*! \file basicos.h
    \brief Tipos de datos basicos.
    \version 1.0
    \author Roflo
Este archivo contiene varios tipos de datos básicos y definiciones necesarias
para el manejo de datos en punto fijo.
*/


Correr programa

Antes de correr el programa, deberán crear un archivo de configuración. Si están en línea de comando, lean ésta información.

Los que estén en Windows, les recomiendo que usen el DoxyWizard.

Enlaces