Históricamente, los ingenieros escribían el código en C, y luego abrían Microsoft Word para escribir el "Manual de Uso de la API" explicando qué hacía cada función. El problema es que al día siguiente, alguien modificaba la función de la válvula para añadirle un nuevo parámetro de seguridad, pero olvidaba actualizar el archivo de Word. A partir de ese momento, la documentación oficial era una mentira, llevando a otros programadores a cometer errores fatales.
Doxygen es un programa de línea de comandos que revolucionó la industria. Opera bajo un principio simple: La documentación debe vivir físicamente pegada al código fuente.
Doxygen escanea todos tus archivos .c y .h buscando un formato de comentario especial que inicia con doble asterisco /**. Utiliza comandos precedidos por @ (como @param para los parámetros de entrada y @return para la salida). Con toda esta información, el motor de Doxygen auto-genera una página web completa (HTML) hipervinculada, hermosa y lista para ser alojada en el servidor de la empresa. Si cambias el código, la documentación se actualiza sola al recompilar.
Ejercicio 1: Tomaremos el módulo hipotético de la Válvula Proporcional de nuestro Despachador de Gas LP. Vamos a adornar su Header File (el Contrato, como vimos en el Día 161) con los bloques de comentarios estrictos de Doxygen. Explicaremos los parámetros, qué devuelve la función, y usaremos la etiqueta @warning para advertir a futuros programadores sobre las consecuencias eléctricas y de seguridad (Norma ATEX) de manipular la válvula incorrectamente.
valvula_proporcional.h
/**
* @file valvula_proporcional.h
* @author Arquitecto Embebidos 365
* @date 10 Septiembre 2026
* @brief Controlador Hardware Abstraction Layer (HAL) para la válvula principal.
*
* @details Este módulo gestiona el actuador electromecánico que controla
* el flujo de Gas LP hacia el vehículo. Utiliza una modulación PWM de
* baja frecuencia para permitir aperturas porcentuales del solenoide.
* Depende estructuralmente del Timer 3 (TIM3) configurado a 1 KHz.
*/
#ifndef VALVULA_PROPORCIONAL_H
#define VALVULA_PROPORCIONAL_H
#include <stdint.h>
#include <stdbool.h>
/**
* @brief Códigos de error devueltos por el subsistema de la válvula.
*/
typedef enum {
VALVULA_OK = 0, /**< Operación completada con éxito */
VALVULA_ERR_PWM_OUT = 1, /**< Porcentaje PWM fuera de rango (0-100) */
VALVULA_ERR_LOCKOUT = 2, /**< El Watchdog metrológico ha bloqueado mecánicamente el equipo */
VALVULA_ERR_HW_FAULT = 3 /**< Falla de aislamiento galvánico o relé soldado */
} ValvulaStatus_t;
/**
* @brief Inicializa los pines GPIO y el Timer PWM asociados a la válvula.
*
* @pre El reloj del sistema (SystemClock) debe estar previamente configurado a 84 MHz.
* @note Esta función fuerza la válvula a un estado inicial de 0% (CERRADA) por seguridad.
*
* @return ValvulaStatus_t Retorna VALVULA_OK si el hardware respondió correctamente al POST.
*/
ValvulaStatus_t Valvula_Init(void);
/**
* @brief Modifica la apertura física de la electroválvula de despacho de Gas LP.
*
* @details Altera el registro Capture/Compare (CCR) del Timer interno para
* modificar el ancho de pulso enviado a la compuerta del MOSFET de potencia.
*
* @param[in] porcentaje Nivel de apertura deseado expresado de 0.0f a 100.0f.
*
* @warning ¡PELIGRO ATEX ZONA 0! La llamada a esta función induce corrientes de hasta 3 Amperios.
* Jamás debe ejecutarse si la bandera de Aislamiento Galvánico reporta fallas en la Barrera Zener.
*
* @retval VALVULA_OK Si la orden fue inyectada al hardware exitosamente.
* @retval VALVULA_ERR_PWM_OUT Si se proporcionó un número negativo o mayor a 100.
* @retval VALVULA_ERR_LOCKOUT Si existe un candado de seguridad metrológico activo.
*/
ValvulaStatus_t Valvula_SetApertura(float porcentaje);
/**
* @brief Cierra inmediatamente la válvula ignorando las rampas de desaceleración.
*
* @details Este es el botón de pánico del sistema. Aplica un 0% inmediato al PWM
* y apaga el pin habilitador maestro del driver del motor.
*/
void Valvula_ParoDeEmergencia(void);
#endif /* VALVULA_PROPORCIONAL_H */
Objetivo del día: Certificabilidad y Handover Técnico Institucional.
Imagina que presentas tu Tesis o intentas vender la patente de tu placa a una gran corporación de energía. Ellos someterán tu proyecto a una auditoría técnica. Si les entregas cientos de archivos `.c` con comentarios desordenados como `// Esta funcion abre la valvula, no le muevas al PWM`, el auditor rechazará el sistema por "falta de mantenibilidad a nivel empresarial".
Al adherirte al **Estándar Doxygen**, puedes abrir una terminal, ejecutar el comando `doxygen Doxyfile`, y en 3 segundos obtienes un sitio web corporativo impecable y navegable. En este sitio, cuando el ingeniero de la corporación hace clic en la función `Valvula_SetApertura`, ve resaltada en rojo brillante la etiqueta `@warning` sobre los riesgos de la Norma ATEX y las Barreras Zener. Has demostrado que tu sistema no solo es un pedazo de silicio funcional, sino un producto industrial maduro que otro equipo de ingenieros puede adoptar, mantener y escalar sin depender de tu presencia en la empresa.
/**. Utiliza etiquetas estandarizadas: @brief para un resumen corto, @details para explicaciones largas, y @param[in/out] para especificar la dirección y propósito de los argumentos.@warning y @pre (Precondiciones) son salvavidas. Documentan requisitos de hardware obligatorios (ej. *El reloj debe estar encendido primero*) y advertencias de seguridad física que el compilador no puede deducir por sí solo.