La documentación de las funciones y clases al programar puede ser una tarea tediosa o incluso aburrida, pero es algo realmente útil por varias razones, obliga a revisar qué hace cada función exactamente, sienta bases para que futuros desarrolladores (o uno mismo en años siguientes) pueda averiguar qué hacía el código.

Doxygen es una herramienta de generación de documentación a partir del código fuente, es decir, no crea la documentación por nosotros, pero es un paso. Es compatible con Java, C++, C# entre otros.

Características:

Multiplataforma (Windows / Mac / Linux)
Compatible con C++, Java, C#, PHP, Objective-C, VHDL… entre otros
Genera diagramas de herencia de manera automática
Exporta a HTML, CHM, RTF, LaTeX, PDF (Vía LaTeX), XML, o incluso páginas de man

Instalación y Uso

Existen varias maneras de usar la herramienta, siendo la más cómoda el asistente visual que incorpora. Usando un simple sistema de menús se pueden configurar las opciones básicas que son:

Project: En este apartado se selecciona el nombre del proyecto, una breve descripción, la versión, el logo, la carpeta donde debe buscar el código y la carpeta donde debe guardar la documentación.
Mode: En este apartado se selecciona el lenguaje de programación en el que está el código, y se selecciona si se quieren mostrar todas las entidades o solo aquellas documentadas, de tal manera que podemos evitar tener valores vacíos solo con el nombre, como pasa en javadoc. Además se puede referenciar directamente al código fuente, para que conecte cada función con la línea de código correspondiente.
Output: En este apartado se puede seleccionar el formato de salida, y las diferentes opciones de generación, siendo los dos apartados mayores HTML y LaTeX, y además pudiendo generar el resto de los formatos vistos anteriormente.
Diagrams: En este apartado se permite personalizar la manera de generar los gráficos y diagramas.

Una vez configuradas dichas opciones, en la pestaña Run se hace click en «Run doxygen» donde, en función de las opciones configuradas se generarán una o varias salidas.

Sintaxis

La transición a partir código comentado para herramientas como Javadoc es automática ya que reconoce los comandos habituales. Si es la primera vez que usa un sistema de generación de documentación puede usar otras notaciones como la de este ejemplo (Escrito en C pero aplicable a otros lenguajes):

/**
 *  A test class. A more elaborate class description.
 */

class Test
{
  public:

    /**
     * An enum.
     * More detailed enum description.
     */

    enum TEnum {
          TVal1, /**&lt; enum value TVal1. */
          TVal2, /**&lt; enum value TVal2. */
          TVal3  /**&lt; enum value TVal3. */
         }
       *enumPtr, /**&lt; enum pointer. Details. */
       enumVar;  /**&lt; enum variable. Details. */

      /**
       * A constructor.
       * A more elaborate description of the constructor.
       */
      Test();

      /**
       * A destructor.
       * A more elaborate description of the destructor.
       */
     ~Test();

      /**
       * a normal member taking two arguments and returning an integer value.
       * @param a an integer argument.
       * @param s a constant character pointer.
       * @see Test()
       * @see ~Test()
       * @see testMeToo()
       * @see publicVar()
       * @return The test results
       */
       int testMe(int a,const char *s);

      /**
       * A pure virtual member.
       * @see testMe()
       * @param c1 the first argument.
       * @param c2 the second argument.
       */
       virtual void testMeToo(char c1,char c2) = 0;

      /**
       * a public variable.
       * Details.
       */
       int publicVar;

      /**
       * a function variable.
       * Details.
       */
       int (*handler)(int a,int b);
};

La salida correspondiente a este código, una vez procesado por Doxygen en formato html se muestra aquí.

Extras

Además de la documentación que generemos a partir de las cabeceras de nuestras funciones, se puede agregar documentación adicional (casos de uso, ejemplos, o imágenes externas), lo que nos permitirá generar, usando solamente nuestro código fuente y los comentarios, una documentación completa que estará siempre actualizada.

Dentro de esta personalización, se puede modificar la página principal, que será la primera referencia a la API del proyecto, usando la siguiente plantilla (Que deberá ser incluida en cualquier fichero de código fuente):

/*! \mainpage My Personal Index Page
 *
 * \section intro_sec Introduction
 *
 * This is the introduction.
 *
 * \section install_sec Installation
 *
 * \subsection step1 Step 1: Opening the box
 *
 * etc...
 */

Cada página adicional se puede generar usando el atributo \page seguido por el nombre de la página y el título de ésta, y enlazarla usando el atributo \link, lo que permite tener una documentación completa más allá de los comentarios de las funciones

Conclusiones

Desde que leí el libro «The pragmatic Programmer» estaba buscando un sistema que me permitiera automatizar la generación de documentación, y Doxygen es un buen candidato, el formato final tiene una sorprendente calidad, además de ser 100% personalizable, incluso puede integrarse con herramientas como Ant (o el equivalente en .net NAnt) para conseguir una generación automática de una versión siempre actualizada de la documentación.