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

main/transport/spi_master.h

@@ -74,6 +74,10 @@ typedef struct {
  */
 class SpiMaster {
 public:
+    /**
+     * @brief 获取 SpiMaster 单例实例。
+     * @return SpiMaster 单例引用。
+     */
     static SpiMaster& instance();
 
     /** @brief 初始化 SPI2 总线与目标从设备。 */
@@ -136,9 +140,21 @@ public:
     spi_device_handle_t deviceHandle() const { return m_spiDevice; }
 
 private:
+    /**
+     * @brief 私有默认构造函数。
+     */
     SpiMaster() = default;
+    /**
+     * @brief 私有析构函数。
+     */
     ~SpiMaster() = default;
+    /**
+     * @brief 禁止复制构造。
+     */
     SpiMaster(const SpiMaster&) = delete;
+    /**
+     * @brief 禁止复制赋值。
+     */
     SpiMaster& operator=(const SpiMaster&) = delete;
 
     spi_device_handle_t m_spiDevice = NULL;
@@ -147,40 +163,132 @@ private:
     // RAII 锁守卫
     class LockGuard {
     public:
+        /**
+         * @brief 构造加锁守卫，获取互斥锁。
+         * @param mutex 互斥锁句柄。
+         */
         explicit LockGuard(SemaphoreHandle_t mutex) : m_lock(mutex) {
             if (m_lock) { xSemaphoreTake(m_lock, portMAX_DELAY); }
         }
+        /**
+         * @brief 析构解锁守卫，释放互斥锁。
+         */
         ~LockGuard() {
             if (m_lock) { xSemaphoreGive(m_lock); }
         }
+        /**
+         * @brief 禁止复制构造。
+         */
         LockGuard(const LockGuard&) = delete;
+        /**
+         * @brief 禁止复制赋值。
+         */
         LockGuard& operator=(const LockGuard&) = delete;
     private:
         SemaphoreHandle_t m_lock;
     };
 
     // 内部 SPI 传输
+    /**
+     * @brief 执行底层 SPI 时钟同步传输。
+     * @param tx_buf 发送数据缓冲区。
+     * @param tx_len 发送数据长度。
+     * @param rx_buf 接收数据缓冲区。
+     * @param rx_len 接收数据长度。
+     * @param timeout_ms 超时时间（毫秒），0 表示无限等待。
+     * @return ESP_OK 表示成功，否则返回错误码。
+     */
     esp_err_t transferClocked(const uint8_t *tx_buf, size_t tx_len,
                               uint8_t *rx_buf, size_t rx_len,
                               uint32_t timeout_ms = 0U);
+    /**
+     * @brief 执行 SPI 请求-响应组合传输。
+     * @param cmd 命令字节（0 表示无命令）。
+     * @param payload 负载数据缓冲区。
+     * @param payload_len 负载数据长度。
+     * @param rx_buf 接收数据缓冲区。
+     * @param rx_len 期望接收的数据长度。
+     * @param timeout_ms 超时时间（毫秒），0 表示无限等待。
+     * @return ESP_OK 表示成功，否则返回错误码。
+     */
     esp_err_t transferRequestResponse(uint8_t cmd, const uint8_t *payload, size_t payload_len,
                                       uint8_t *rx_buf, size_t rx_len,
                                       uint32_t timeout_ms = 0U);
 
 
     // 无锁内部版本（供已持锁的公共方法调用，避免递归死锁）
+    /**
+     * @brief 无锁版本的同步 SPI 传输（调用者须已持有锁）。
+     * @param cmd 命令字节。
+     * @param payload 负载数据缓冲区。
+     * @param payload_len 负载数据长度。
+     * @param recv_buf 接收数据缓冲区。
+     * @param recv_len 接收数据长度。
+     * @param timeout_ms 超时时间（毫秒）。
+     * @return ESP_OK 表示成功，否则返回错误码。
+     */
     esp_err_t syncTransferUnlocked(uint8_t cmd, const uint8_t *payload,
                                    size_t payload_len, uint8_t *recv_buf,
                                    size_t recv_len, uint32_t timeout_ms);
+    /**
+     * @brief 无锁版本的 SPI 发送（调用者须已持有锁）。
+     * @param cmd 命令字节。
+     * @param payload 负载数据缓冲区。
+     * @param len 负载数据长度。
+     * @return ESP_OK 表示成功，否则返回错误码。
+     */
     esp_err_t sendUnlocked(uint8_t cmd, const uint8_t *payload, size_t len);
+    /**
+     * @brief 无锁版本的 OTA 响应轮询（调用者须已持有锁）。
+     * @param resp_type 输出响应类型。
+     * @param resp_payload 输出响应负载缓冲区。
+     * @param resp_max 响应负载缓冲区最大长度。
+     * @param resp_len 输出实际响应长度。
+     * @param timeout_ms 超时时间（毫秒）。
+     * @return ESP_OK 表示成功，否则返回错误码。
+     */
     esp_err_t otaPollResponseUnlocked(uint8_t *resp_type, uint8_t *resp_payload,
                                       size_t resp_max, size_t *resp_len, uint32_t timeout_ms);
     // OTA 帧工具（静态，无状态）
+    /**
+     * @brief 计算 OTA 帧的 8 位 CRC 校验和。
+     * @param data 数据缓冲区。
+     * @param len 数据长度。
+     * @return 计算得到的 CRC 值。
+     */
     static uint8_t otaCrc8(const uint8_t *data, size_t len);
+    /**
+     * @brief 构建 OTA 协议帧。
+     * @param type 帧类型。
+     * @param payload 负载数据缓冲区。
+     * @param payload_len 负载数据长度。
+     * @param out 输出帧缓冲区。
+     * @param out_len 输出实际帧长度。
+     * @return true 表示构建成功，false 表示失败。
+     */
     static bool otaBuildFrame(uint8_t type, const uint8_t *payload, size_t payload_len,
                               uint8_t *out, size_t *out_len);
+    /**
+     * @brief 解析 OTA 协议帧。
+     * @param frame 帧数据缓冲区。
+     * @param frame_len 帧数据长度。
+     * @param type 输出解析得到的帧类型。
+     * @param payload 输出指向负载数据的指针。
+     * @param payload_len 输出负载数据长度。
+     * @return true 表示解析成功，false 表示失败。
+     */
     static bool otaParseFrame(const uint8_t *frame, size_t frame_len,
                               uint8_t *type, const uint8_t **payload, size_t *payload_len);
+    /**
+     * @brief 在数据缓冲区中搜索并解析 OTA 帧。
+     * @param buf 数据缓冲区。
+     * @param buf_len 数据缓冲区长度。
+     * @param type 输出帧类型。
+     * @param payload 输出指向负载数据的指针。
+     * @param payload_len 输出负载数据长度。
+     * @param frame_offset 输出帧在缓冲区中的偏移位置。
+     * @return true 表示找到并成功解析，false 表示未找到。
+     */
     static bool otaFindFrame(const uint8_t *buf, size_t buf_len,
                              uint8_t *type, const uint8_t **payload, size_t *payload_len,
                              size_t *frame_offset);