docs(ota_mutex): 添加函数注释说明

2026-06-15 01:14:29 +08:00
parent 929faf1d38
commit 2875ef2145
17 changed files with 1026 additions and 0 deletions
@@ -33,6 +33,10 @@ static const char *TAG = "DEBUG_LOG";
 // ============================================================
 // 单例
 // ============================================================
+/**
+  * @brief 获取 DebugLog 单例实例。
+ * @return DebugLog 引用。
+ */
 DebugLog& DebugLog::instance()
 {
    static DebugLog inst;
@@ -42,6 +46,10 @@ DebugLog& DebugLog::instance()
 // ============================================================
 // 日志环形缓冲区（供 HTTP /logs 拉取）
 // ============================================================
+/**
+  * @brief 获取当前环形日志缓冲区中的日志条数。
+ * @return 日志条数。
+ */
 int DebugLog::ringCount()
 {
    if (!m_logRingMutex) return 0;
@@ -51,6 +59,11 @@ int DebugLog::ringCount()
    return count;
 }

+/**
+  * @brief 读取并清空环形日志缓冲区，返回 JSON 数组字符串。
+ * @param out_len 输出参数，返回 JSON 字符串长度。
+ * @return 指向 JSON 字符串的指针，需调用者 free。
+ */
 char *DebugLog::ringDrainJson(int *out_len)
 {
    if (!m_logRingMutex) {
@@ -117,6 +130,11 @@ char *DebugLog::ringDrainJson(int *out_len)
    return json;
 }

+/**
+  * @brief 向环形日志缓冲区中推送一条日志数据。
+ * @param data 日志数据指针。
+ * @param len 数据长度。
+ */
 void DebugLog::ringPush(const char *data, int len)
 {
    if (!m_logRingMutex || len <= 0) return;
@@ -139,6 +157,10 @@ void DebugLog::ringPush(const char *data, int len)
 // ============================================================
 // UART 调试日志
 // ============================================================
+/**
+  * @brief 初始化 UART0 调试串口。
+ * @return esp_err_t 错误码。
+ */
 esp_err_t DebugLog::uartInit()
 {
    if (m_uartInitialized) {
@@ -180,6 +202,12 @@ esp_err_t DebugLog::uartInit()
    return ESP_OK;
 }

+/**
+  * @brief 通过 UART0 直接发送原始字节数据。
+ * @param data 待发送数据指针。
+ * @param len 数据长度。
+ * @return esp_err_t 错误码。
+ */
 esp_err_t DebugLog::uartSend(const uint8_t *data, size_t len)
 {
    if (!m_uartInitialized) {
@@ -197,6 +225,10 @@ esp_err_t DebugLog::uartSend(const uint8_t *data, size_t len)
 // ============================================================
 // 初始化（UART 立即可用，UDP socket 延迟到首次发送时创建）
 // ============================================================
+/**
+  * @brief 初始化日志系统，包括 UART 输出、UDP 目标和内部缓冲区。
+ * @return esp_err_t 错误码。
+ */
 esp_err_t DebugLog::init()
 {
    if (m_initialized) {
@@ -219,6 +251,10 @@ esp_err_t DebugLog::init()
    return ESP_OK;
 }

+/**
+  * @brief 确保 UDP socket 已创建（延迟创建）。
+ * @return esp_err_t 错误码。
+ */
 esp_err_t DebugLog::ensureUdpSocket()
 {
    if (m_udpSock >= 0) {
@@ -235,6 +271,12 @@ esp_err_t DebugLog::ensureUdpSocket()
    return ESP_OK;
 }

+/**
+  * @brief 发送原始日志数据到底层输出通道。
+ * @param data 待发送数据指针。
+ * @param len 数据长度。
+ * @return esp_err_t 错误码。
+ */
 esp_err_t DebugLog::send(const uint8_t *data, size_t len)
 {
    esp_err_t udp_ret = ESP_FAIL;
@@ -270,6 +312,13 @@ esp_err_t DebugLog::send(const uint8_t *data, size_t len)
    return ESP_FAIL;
 }

+/**
+  * @brief 按日志级别与标签格式化输出一条日志。
+ * @param level 日志级别。
+ * @param tag 日志标签。
+ * @param fmt 格式化字符串。
+ * @param ... 可变参数。
+ */
 void DebugLog::log(debug_log_level_t level, const char *tag, const char *fmt, ...)
 {
    if (!m_initialized) {
@@ -48,6 +48,10 @@ typedef enum {
 */
 class DebugLog {
 public:
+    /**
+      * @brief 获取 DebugLog 单例实例。
+     * @return DebugLog 引用。
+     */
    static DebugLog& instance();

    /** @brief 初始化日志系统，包括 UART 输出、UDP 目标和内部缓冲区。 */
@@ -23,6 +23,10 @@
 // ============================================================
 // 单例
 // ============================================================
+/**
+  * @brief 获取 HealthMonitor 单例实例。
+ * @return HealthMonitor 引用。
+ */
 HealthMonitor& HealthMonitor::instance()
 {
    static HealthMonitor inst;
@@ -32,6 +36,9 @@ HealthMonitor& HealthMonitor::instance()
 // ============================================================
 // 初始化
 // ============================================================
+/**
+  * @brief 初始化健康监控模块，创建内部互斥锁与基础状态。
+ */
 void HealthMonitor::init()
 {
    m_mutex = xSemaphoreCreateMutex();
@@ -43,6 +50,10 @@ void HealthMonitor::init()
 // ============================================================
 // 线程安全的健康状态读写
 // ============================================================
+/**
+  * @brief 加锁读取当前健康状态。
+ * @return 当前健康状态。
+ */
 health_state_t HealthMonitor::getState()
 {
    if (m_mutex) xSemaphoreTake(m_mutex, portMAX_DELAY);
@@ -51,6 +62,10 @@ health_state_t HealthMonitor::getState()
    return s;
 }

+/**
+  * @brief 加锁设置健康状态。
+ * @param newState 新的健康状态。
+ */
 void HealthMonitor::setState(health_state_t newState)
 {
    if (m_mutex) xSemaphoreTake(m_mutex, portMAX_DELAY);
@@ -61,11 +76,19 @@ void HealthMonitor::setState(health_state_t newState)
 // ============================================================
 // 获取当前健康状态（public 接口）
 // ============================================================
+/**
+  * @brief 获取当前系统健康状态（线程安全）。
+ * @return 当前健康状态。
+ */
 health_state_t HealthMonitor::getCurrent()
 {
    return getState();
 }

+/**
+  * @brief 获取最近一次芯片温度。
+ * @return 温度值（摄氏度）。
+ */
 float HealthMonitor::getLastTemperature()
 {
    if (m_mutex) xSemaphoreTake(m_mutex, portMAX_DELAY);
@@ -74,6 +97,12 @@ float HealthMonitor::getLastTemperature()
    return t;
 }

+/**
+  * @brief 获取最近一次 WiFi RSSI 及其年龄。
+ * @param out_rssi 输出参数，返回 RSSI 值。
+ * @param out_age_ms 输出参数，返回样本年龄（毫秒）。
+ * @return 是否有有效数据。
+ */
 bool HealthMonitor::getLastWifiRssi(int8_t *out_rssi, uint32_t *out_age_ms)
 {
    if (m_mutex) xSemaphoreTake(m_mutex, portMAX_DELAY);
@@ -96,6 +125,10 @@ bool HealthMonitor::getLastWifiRssi(int8_t *out_rssi, uint32_t *out_age_ms)
 // ============================================================
 // 温度监控（定时器回调）
 // ============================================================
+/**
+  * @brief 温度监控定时器回调函数。
+ * @param arg 用户参数（未使用）。
+ */
 void HealthMonitor::tempMonitorCallback(void *arg)
 {
    auto& self = instance();
@@ -127,6 +160,10 @@ void HealthMonitor::tempMonitorCallback(void *arg)
 // ============================================================
 // FreeRTOS 任务入口
 // ============================================================
+/**
+  * @brief 健康监控 FreeRTOS 任务入口。
+ * @param pvParameters 任务参数。
+ */
 void HealthMonitor::taskEntry(void *pvParameters)
 {
    auto& self = instance();
@@ -173,6 +210,11 @@ void HealthMonitor::taskEntry(void *pvParameters)
 // ============================================================
 // 健康事件日志
 // ============================================================
+/**
+  * @brief 记录一条健康事件日志。
+ * @param event 事件名称。
+ * @param value 事件值。
+ */
 void HealthMonitor::logEvent(const char *event, int value)
 {
    DEBUG_INFO("HEALTH", "[健康事件] %s: %d", event, value);
@@ -181,6 +223,10 @@ void HealthMonitor::logEvent(const char *event, int value)
 // ============================================================
 // OTA 健康检查
 // ============================================================
+/**
+  * @brief OTA 传输前执行健康检查。
+ * @return 健康检查状态。
+ */
 health_status_t HealthMonitor::checkBeforeOta()
 {
    health_status_t status = HEALTH_MON_OK;
@@ -227,6 +273,10 @@ health_status_t HealthMonitor::checkBeforeOta()
    return status;
 }

+/**
+  * @brief OTA 中继转发阶段执行健康检查（跳过 WiFi 检查）。
+ * @return 健康检查状态。
+ */
 health_status_t HealthMonitor::checkBeforeOtaRelay()
 {
    health_status_t status = HEALTH_MON_OK;
@@ -261,6 +311,11 @@ health_status_t HealthMonitor::checkBeforeOtaRelay()
 // ============================================================
 // WiFi RSSI 更新
 // ============================================================
+/**
+  * @brief 根据 WiFi RSSI 更新健康状态。
+ * @param rssi WiFi RSSI 值。
+ * @return 健康检查状态。
+ */
 health_status_t HealthMonitor::updateFromWifiRssi(int8_t rssi)
 {
    if (rssi < WIFI_RSSI_CRITICAL) {
@@ -37,6 +37,10 @@ typedef enum {
 */
 class HealthMonitor {
 public:
+    /**
+      * @brief 获取 HealthMonitor 单例实例。
+     * @return HealthMonitor 引用。
+     */
    static HealthMonitor& instance();

    /** @brief 初始化健康监控模块，创建内部互斥锁与基础状态。 */