Para documentar el código se utilizará el software Doxygen (https://www.doxygen.nl/). Este software permite la mezcla del código con la documentación, además de poder generar una documentación aparte.

Toda la documentación generada se considera exclusivamente de uso interno y no debe ser compartida con cualquier persona o entidad externa a la organización.

La documentación deberá ser escrita en un lenguaje común para todos los participantes.

Las etiquetas puestas en los apartados siguientes son obligatorias (a menos que se diga lo contrario), además de estas se podrá incluir otras etiquetas con más información para ampliar la comprensión del código.

La documentación estará siempre dentro de los símbolos de comentario /** y */. Para documentar variables o partes dentro de una estructura o unión se podrá utilizar el símbolo ///< (sólo permite una línea).

Es recomendable utilizar las siguientes etiquetas para indicar que tipo de bloque de comentario se está realizando:

@struct : para documentar estructuras en C.
@union : para documentar uniones.
@enum : para documentar enumeraciones.
@fn : para documentar funciones.
@var : para documentar variables, o valores de tipo typedef o enum.
@def : para documentar #define (constantes, macros, etc.).
@typedef : para documentar una definición de tipo.
@file : para documentar un fichero.

Para realizar gráficos de apoyo se podrán utilizar las etiquetas: @image, o el lenguaje de generación de gráficos PlantUML (https://plantuml.com/es/).

Documentación de ficheros

Todos los ficheros incluidos en el código deben tener una cabecera con los siguientes parámetros:

@file : Nombre del fichero
@brief : Descripción breve del propósito de la función.
@description : Descripción ampliada (opcional) del propósito del fichero. En este punto se incluirán los gráficos o referencias externas que fueran necesarias para entender el funcionamiento.

Documentación de variables globales

Todas las variables globales deben estar documentadas, se deberá incluir información de su propósito o uso. Es recomendable que esta información vaya precedida con la etiqueta @var y el nombre de la variable.

Documentación de constantes

Todas las constantes deben estar documentadas, se deberá incluir información de su propósito o uso. Es recomendable que esta información vaya precedida con la etiqueta @def y el nombre de la constante.

Documentación de funciones públicas

Todas las funciones públicas, es decir las no definidas como static o que puedan “verse” desde otras partes del código. Deberán llevar obligatoriamente la siguiente documentación:

@brief : Descripción breve del propósito de la función.
@description : Descripción ampliada (opcional) del propósito de la función. En este punto se incluirán los gráficos o referencias externas que fueran necesarias para entender el funcionamiento.
@param : parámetros de entrada o salida de la función. Se deberá usar una etiqueta @param para cada uno de los parámetros definidos en la cabecera de la función. Se deberá especificar el tipo de parámetro y los valores aceptados (si los hubiera).
- [in] : esta etiqueta servirá para marcar los parámetros de entrada
- [out] : esta etiqueta servirá para marcar los parámetros que se utilicen únicamente como variables de retorno.
- [io] : esta etiqueta servirá para marcar los parámetros que tengan información utilizable en la función y que además se utilice como variable de retorno.
@return : valor devuelto de la función. Se deberá especificar el tipo de parámetro devuelto y los valores aceptados.
@see : (opcional) en caso que se utilicen variables globales se deberá usar una etiqueta @see (o @sa) en la documentación de la función para remarcar este uso y crear un vínculo con la variable global utilizada. Esta etiqueta también podrá ser utilizada para crear un vínculo con otras funciones con las que esté fuertemente relacionada.

Es recomendable crear un gráfico de llamada para las funciones de tal forma que quede reflejado desde dónde y cómo se utiliza cada función.

@callgraph : genera un gráfico que muestra las funciones que son llamadas por la función actual (directa o indirectamente).
@callergraph : genera un gráfico que muestra las funciones que llaman a la función actual (directa o indirectamente).

Documentación de funciones de máquinas de estado

Las funciones que implementan máquinas de estado son funciones especiales que reaccionan no sólo en función de los parámetros de entrada que tienen, sino también del estado en el que se encuentra. Las funciones que implementan las máquinas de estado deberán llevar obligatoriamente la siguiente documentación:

@brief : Descripción breve del propósito de la función.
@description : Descripción ampliada de funcionamiento de la máquina de estados. En este punto se debe incluir un gráfico (mediante la etiqueta @image o el lenguaje PlantUML) que explique el flujo de la máquina de estados y además de podrán incluir otros gráficos o referencias externas que fueran necesarias para entender el funcionamiento.
@param : parámetros de entrada o salida de la función. Se deberá usar una etiqueta @param para cada uno de los parámetros definidos en la cabecera de la función. Se deberá especificar el tipo de parámetro y los valores aceptados (si los hubiera).
- [in] : esta etiqueta servirá para marcar los parámetros de entrada
- [out] : esta etiqueta servirá para marcar los parámetros que se utilicen únicamente como variables de retorno.
- [io] : esta etiqueta servirá para marcar los parámetros que tengan información utilizable en la función y que además se utilice como variable de retorno.
@return : valor devuelto de la función. Se deberá especificar el tipo de parámetro devuelto y los valores aceptados
@see : Se debe utilizar esta etiqueta para crear un vínculo con lavariable de estado (variable que guarda el estado de la máquina) en el caso que sea una variable global. Además si se utilizan variables globales (públicas) dentro de la función, se deberá usar una etiqueta @see (o @sa) en la documentación, para remarcar este uso y crear un vínculo con la variable global utilizada. Esta etiqueta también podrá ser utilizada para crear un vínculo con otras funciones con las que esté fuertemente relacionada.
@startuml/@enduml o @image : Se utilizarán esas etiquetas para dibujar el gráfico de funcionamiento de la máquina de estados, ya sea mediante el lenguaje PlantUML o mediante un programa externo (y se incluya como una imágen).