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

main/server/ble_ota.cpp

@@ -71,6 +71,10 @@ static void sendWindowAck(uint8_t cmd, uint16_t seq, uint32_t completed_bytes);
 static void sendFinishEvent(uint8_t stage, uint32_t value);
 
 // ============================================================
+/**
+  * @brief 获取 BleOta 单例实例。
+ * @return BleOta 类引用。
+ */
 BleOta& BleOta::instance()
 {
     static BleOta inst;
@@ -103,6 +107,10 @@ static void ble_esp32_restart_task(void *pvParameters)
     // 不会返回
 }
 
+/**
+  * @brief 异步完成 ESP32 OTA 收尾并触发重启。
+ * @param pvParameters 前端 SHA-256 十六进制字符串（堆分配，任务负责释放）。
+ */
 static void ble_esp32_finish_and_reboot_task(void *pvParameters)
 {
     // pvParameters: heap-allocated char[65] frontend SHA hex string (or nullptr)

main/server/ble_ota.h

@@ -14,12 +14,37 @@
 
 class BleOta {
 public:
+    /**
+  * @brief 获取 BleOta 单例实例。
+ * @return BleOta 类引用。
+ */
     static BleOta& instance();
 
+    /**
+  * @brief BLE OTA FreeRTOS 任务入口。
+ * @param pvParameters 任务参数，未使用。
+ */
     static void taskEntry(void *pvParameters);
+    /**
+  * @brief 启动 BLE GATT 服务器并注册 OTA 服务。
+ * @return ESP_OK 成功，其他失败。
+ */
     esp_err_t serverStart();
+    /**
+  * @brief 通过 BLE Notify 推送响应数据。
+ * @param data 待推送的数据指针。
+ * @param len 数据长度。
+ * @return ESP_OK 成功，其他失败。
+ */
     esp_err_t notifyResponse(const uint8_t *data, size_t len);
+    /**
+  * @brief 检查 BLE 客户端连接状态。
+ * @return 已连接返回 true，未连接返回 false。
+ */
     bool isConnected();
+    /**
+  * @brief 触发中继模块向 GD32 转发固件。
+ */
     void signalRelay();
 
     // 以下状态为 public，供 C 回调函数访问

main/server/wifi_ota.cpp

@@ -34,6 +34,10 @@
 
 
 // ============================================================
+/**
+  * @brief 获取 WifiOta 单例实例（静态局部变量实现）。
+ * @return WifiOta 单例引用。
+ */
 WifiOta& WifiOta::instance()
 {
     static WifiOta inst;
@@ -42,6 +46,12 @@ WifiOta& WifiOta::instance()
 
 static constexpr uint32_t GD32_OTA_FLASH_SECTOR_SIZE = 4096U;
 
+/**
+  * @brief 按指定对齐值向上取整。
+ * @param value 待对齐的值。
+ * @param alignment 对齐字节数。
+ * @return 对齐后的值。
+ */
 static uint32_t align_up_u32(uint32_t value, uint32_t alignment)
 {
     return ((value + alignment - 1U) / alignment) * alignment;

main/server/wifi_ota.h

@@ -21,31 +21,71 @@ typedef enum {
 
 class WifiOta {
 public:
+    /**
+      * @brief 获取 WifiOta 单例实例。
+     * @return WifiOta 单例引用。
+     */
     static WifiOta& instance();
 
+    /**
+      * @brief 在调度器启动前初始化 WiFi 并尝试 STA 连接。
+     * @return true 表示 STA 初始化中，false 需回退至 AP 模式。
+     */
     bool earlyInit();
+    /**
+      * @brief WiFi OTA FreeRTOS 任务入口，提供 HTTP 上传和中继触发。
+     * @param pvParameters FreeRTOS 任务参数。
+     */
     static void taskEntry(void *pvParameters);
+    /**
+      * @brief 通知 OTA 中继开始向 GD32 转发固件。
+     */
     void signalRelay();
 
+    /**
+      * @brief 获取当前 WiFi 工作模式。
+     * @return 当前 WiFi 模式（AP 或 STA）。
+     */
     static ota_wifi_mode_t getMode();
+    /**
+      * @brief 获取当前 WiFi 信号强度。
+     * @return 信号强度值（dBm）。
+     */
     static int8_t getRssi();
+    /**
+      * @brief 判断 STA 是否已连接到上级 WiFi。
+     * @return true 已连接，false 未连接。
+     */
     static bool isConnected();
 
     // ── WiFi 连接状态（WiFi 事件回调 / HTTP / reconnect task 共享，需 mutex 保护）──
+    /** @brief 获取 STA 连接状态。 */
     bool getStaConnected() const          { return m_staConnected.load(); }
+    /** @brief 设置 STA 连接状态。 */
     void setStaConnected(bool v)          { m_staConnected.store(v); }
+    /** @brief 获取 STA 重试次数。 */
     int  getStaRetryCount() const         { return m_staRetryCount.load(); }
+    /** @brief 设置 STA 重试次数。 */
     void setStaRetryCount(int v)          { m_staRetryCount.store(v); }
+    /** @brief 获取 STA 重试是否已耗尽。 */
     bool getStaRetryExhausted() const     { return m_staRetryExhausted.load(); }
+    /** @brief 设置 STA 重试耗尽标志。 */
     void setStaRetryExhausted(bool v)     { m_staRetryExhausted.store(v); }
+    /** @brief 获取 GD32 固件存储完成标志。 */
     bool getGd32StorageDone() const       { return m_gd32StorageDone.load(); }
+    /** @brief 设置 GD32 固件存储完成标志。 */
     void setGd32StorageDone(bool v)       { m_gd32StorageDone.store(v); }
+    /** @brief 获取中继触发标志。 */
     bool getRelayTriggered() const        { return m_relayTriggered.load(); }
+    /** @brief 设置中继触发标志。 */
     void setRelayTriggered(bool v)        { m_relayTriggered.store(v); }
 
     // ── 状态互斥锁（保护复合读-改-写操作）──
+    /** @brief 获取状态互斥锁句柄。 */
     SemaphoreHandle_t getStateMutex() const { return m_stateMutex; }
+    /** @brief 锁定状态互斥锁。 */
     void stateLock()   { if (m_stateMutex) xSemaphoreTake(m_stateMutex, portMAX_DELAY); }
+    /** @brief 解锁状态互斥锁。 */
     void stateUnlock() { if (m_stateMutex) xSemaphoreGive(m_stateMutex); }
 
     // ── 初始化/运行时状态（仅 OTA 任务访问，无需额外锁）──
@@ -66,13 +106,44 @@ private:
     std::atomic<bool> m_relayTriggered{false};
     SemaphoreHandle_t m_stateMutex = NULL;
 
+    /**
+      * @brief 初始化 SoftAP 模式，供局域网 OTA 使用。
+     */
     void initAp();
+    /**
+      * @brief 初始化 STA 模式并连接预配置路由器。
+     * @return ESP_OK 成功，其他失败。
+     */
     esp_err_t initSta();
+    /**
+      * @brief 设置 STA 静态 IP、网关和子网掩码。
+     */
     void setStaticIp();
+    /**
+      * @brief WiFi/IP 事件回调，处理连接、断开和 IP 获取。
+     * @param arg 回调用户参数。
+     * @param event_base 事件基类。
+     * @param event_id 具体事件 ID。
+     * @param event_data 事件附带数据。
+     */
     static void wifiEventHandler(void *arg, esp_event_base_t event_base,
                                  int32_t event_id, void *event_data);
+    /**
+      * @brief STA 后台重连任务，处理退避延迟和重连。
+     * @param pvParameters FreeRTOS 任务参数。
+     */
     static void reconnectTask(void *pvParameters);
+    /**
+      * @brief 启动 HTTP OTA 服务器，注册各接口路由。
+     * @return ESP_OK 成功，其他失败。
+     */
     esp_err_t httpServerStart();
+    /**
+      * @brief 等待 STA 连接成功并获取 IP 地址。
+     * @param ip_str 输出缓冲区，存放 IP 字符串。
+     * @param ip_len 缓冲区长度。
+     * @return ESP_OK 连接成功，ESP_ERR_TIMEOUT 超时。
+     */
     esp_err_t waitStaConnected(char *ip_str, size_t ip_len);
 };