Jujube: Generar documentación para nuestros juegos a partir del código fuente con Doxygen

Doxygen es una herramienta que nos va a permitir generar documentación a partir de nuestro código fuente en c, aunque es compatible con una gran cantidad de lenguajes más como PHP, C++, etc. Y esta disponible tanto para Windows, linux y Mac.

Esta documentación puede sernos de mucha utilidad de cara a documentar el código de nuestros juegos y poder reutilizar su código fuente, descubrí esta herramienta por casualidad buscando un equivalente al Javadoc de java en C.

Sus principales características son

Puede generar un navegador de documentación en línea (en HTML) y/o un manual de referencia fuera de línea (en LaTex)
Doxygen para extraer la estructura del código de archivos fuente no documentados y también puede visualizar las relaciones entre los diversos elementos mediante la inclusión de gráficos de dependencia, diagramas de herencia y diagramas de colaboración, que se generan automáticamente.
También puede usar Doxygen para crear documentación normal

Un ejemplo muyu claro de la documentación que genera podria ser la documentacion del Api KDE que esta elaborada con esta herramienta https://api.kde.org/

Puedes descargarte Doxygen desde el siguiente enlace: https://doxygen.nl/download.html

Bloque de comentarios especial de Doxygen

Para poder poner comentarios en su código para que doxygen los incorpore en la documentación que genera debemos añadir un bloque de comentarios especial, este bloque se asemeja a un bloque de comentarios de estilo C o C++ con algunas marcas adicionales, por lo que doxygen sabe que es un fragmento de texto estructurado que debe terminar en la documentación generada.

Podemos usar el estilo Javadoc para ello, que consiste en un bloque de comentarios de estilo C que comienza con dos *, como este:

/**
 * ... texto ...
 */

Doxygen incluye una sintaxis propia dentro de los bloques de comentarios especiales, a continuación dejo un ejemplo extraído de su documentación:


/**
  @brief Writes the digital output of a given line in a given subdevice

  Most digital output systems are organized in groups of lines, (8, 16, 32 ...) and the aim of this function is to handle only
  one line a given group

  @param subdevice target subdevice, an integer between 0 and 255
  @param line line to be modifided, in general, a value between 0 and 31, but depends on the target slave
  @param value state to be written to thew line, mus be 0 or 1

  @returns the result of the operation, being cd_Error_NoError if all worked OK

  Example:
  \verbatim
      cd_Error my_error;

      my_error = cdm_DAQWriteDigitalLine(2,31,1);
      if (my_error != CD_Erro_NoError) {
            printf("Ups, this failed with error %s\n", cd_ErrorStr(my_error);
      }
   \endverbatim

  */
cd_Error cdm_DAQWriteDigitalLine(uint8_t subdevice, uint8_t line, uint8_t value) {
 ...

}

Para aprender esta sintaxis os recomiendo que le deis un vistazo a la documentación oficial en: https://doxygen.nl/manual/index.html

Lanzando el generador de HTML

Para lanzar el generador de HTML se procede con los siguientes pasos minimos desde el GUI una vez descargado y instalado:

1. Indicamos el nombre de nuestro proyecto

2. Especificamos el lenguaje de programación, en nuestro caso C.

3. Seleccionar la forma de salida (en nuestro caso no tocamos nada)

4. Seleccionar diagramas de salida (en nuestro caso no tocamos nada)

5. En el ultimo paso pulsamos el botón “run doxygen” y si queremos ver el resultado del html generado, una vez terminado el proceso pulsamos el botón “Show HTML output”