refactor(gml670x4): 将函数注释统一迁移到源文件

inc/ads1256.h

@@ -4,52 +4,11 @@
 /* sensor.c 切换通道时需要此寄存器地址 */
 #define ADS1256_REG_MUX 0x01
 
-/**
- * @brief 初始化 ADS1256：配置 GPIO/SPI，复位芯片，写入寄存器，自校准。
- * @return 0 成功，负 errno 失败。
- */
 int ads1256_init(void);
-
-/**
- * @brief 等待 DRDY 拉低（转换结果可读），带超时保护。
- * @param timeout_ms 超时时间（毫秒）。
- * @return 0 成功，-ETIMEDOUT 超时。
- */
 int ads1256_wait_drdy(uint16_t timeout_ms);
-
-/**
- * @brief 向 ADS1256 写单个寄存器。
- * @param reg 目标寄存器地址。
- * @param val 要写入的值。
- */
 void ads1256_write_reg(uint8_t reg, uint8_t val);
-
-/**
- * @brief 从 ADS1256 读单个寄存器。
- * @param reg 目标寄存器地址。
- * @return 寄存器值。
- */
 uint8_t ads1256_read_reg(uint8_t reg);
-
-/**
- * @brief 发送 SYNC + WAKEUP 命令，触发一次同步采样。
- */
 void ads1256_sync_wakeup(void);
-
-/**
- * @brief 硬件复位 ADS1256（通过 RESET 引脚），等待复位后自校准完成。
- * @return 0 成功，-ETIMEDOUT 芯片无响应。
- */
 int ads1256_hwreset(void);
-
-/**
- * @brief 读取当前 24 位转换结果，符号扩展为 int32_t。
- * @return ADC 原始值。
- */
 int32_t ads1256_read_data(void);
-
-/**
- * @brief 发送单字节命令到 ADS1256。
- * @param cmd 命令字。
- */
 void ads1256_write_cmd(uint8_t cmd);

inc/ble_transport.h

@@ -2,27 +2,9 @@
 #include <stdbool.h>
 #include <stdint.h>
 
-/**
- * @brief 初始化 BLE 协议栈、NUS 服务和内部状态。
- * @return 0 成功，负 errno 失败。
- */
 int ble_transport_init(void);
-
-/**
- * @brief 启动 BLE 广播。
- */
 void ble_transport_adv_start(void);
-
-/**
- * @brief 通过 NUS 发送二进制帧，自动重试最多 3 次。未连接或通知未开启时静默丢弃。
- * @param data 待发送字节缓冲区。
- * @param len  字节数。
- */
 void ble_transport_send(const uint8_t *data, uint16_t len);
-
-/**
- * @brief 检查是否已连接且通知已使能。
- */
 bool ble_transport_is_ready(void);
 
 /* --- 下行参数 getter --- */

inc/button.h

@@ -1,7 +1,3 @@
 #pragma once
 
-/**
- * @brief 初始化按键模块：Button1 按下触发去皮 + LED1 闪烁反馈。
- * @return 0 成功，负 errno 失败。
- */
 int button_init(void);

inc/sensor.h

@@ -1,14 +1,4 @@
 #pragma once
 
-/**
- * @brief 初始化压力传感器模块：ADS1256 硬件 + 初始去皮 + 创建采集线程。
- *
- * 调用后采集线程自动启动，以 50 Hz 循环采集 → CoP → BLE 发送。
- * @return 0 成功，负 errno 失败。
- */
 int sensor_init(void);
-
-/**
- * @brief 执行四路去皮（零点校准），可从任意线程调用。
- */
 void sensor_perform_tare(void);

src/ads1256.c

@@ -32,6 +32,14 @@ static const struct gpio_dt_spec cs_spec    = GPIO_DT_SPEC_GET(DT_ALIAS(ads_cs),
 static const struct gpio_dt_spec drdy_spec  = GPIO_DT_SPEC_GET(DT_ALIAS(ads_drdy), gpios);
 static const struct gpio_dt_spec reset_spec = GPIO_DT_SPEC_GET(DT_ALIAS(ads_reset), gpios);
 
+/**
+ * @brief 等待 DRDY 拉低（转换结果可读），带超时保护。
+ *
+ * @param timeout_ms 超时时间（毫秒）。
+ *
+ * @retval 0 DRDY 在超时前变为可读状态。
+ * @retval -ETIMEDOUT 超时后仍未等到本次转换结果。
+ */
 int ads1256_wait_drdy(uint16_t timeout_ms) {
     /* drdy_spec 配了 GPIO_ACTIVE_LOW，逻辑 1 表示 DRDY 有效（物理拉低） */
     int64_t deadline = k_uptime_get() + timeout_ms;
@@ -45,6 +53,12 @@ int ads1256_wait_drdy(uint16_t timeout_ms) {
     return 0;
 }
 
+/**
+ * @brief 向 ADS1256 写单个寄存器。
+ *
+ * @param reg 目标寄存器地址。
+ * @param val 要写入的寄存器值。
+ */
 void ads1256_write_reg(uint8_t reg, uint8_t val) {
     ads1256_wait_drdy(50);
     gpio_pin_set_dt(&cs_spec, 1);
@@ -57,6 +71,13 @@ void ads1256_write_reg(uint8_t reg, uint8_t val) {
     k_busy_wait(2);
 }
 
+/**
+ * @brief 从 ADS1256 读单个寄存器。
+ *
+ * @param reg 目标寄存器地址。
+ *
+ * @return 读取到的寄存器值。
+ */
 uint8_t ads1256_read_reg(uint8_t reg) {
     ads1256_wait_drdy(50);
     gpio_pin_set_dt(&cs_spec, 1);
@@ -74,6 +95,11 @@ uint8_t ads1256_read_reg(uint8_t reg) {
     return rx_val;
 }
 
+/**
+ * @brief 发送单字节命令到 ADS1256。
+ *
+ * @param cmd 命令字。
+ */
 void ads1256_write_cmd(uint8_t cmd) {
     ads1256_wait_drdy(50);
     gpio_pin_set_dt(&cs_spec, 1);
@@ -83,6 +109,11 @@ void ads1256_write_cmd(uint8_t cmd) {
     gpio_pin_set_dt(&cs_spec, 0);
 }
 
+/**
+ * @brief 发送 SYNC + WAKEUP 命令，触发一次同步采样。
+ *
+ * @return 无返回值。
+ */
 void ads1256_sync_wakeup(void) {
     uint8_t cmd_sync         = CMD_SYNC;
     uint8_t cmd_wakeup       = CMD_WAKEUP;
@@ -98,6 +129,12 @@ void ads1256_sync_wakeup(void) {
     gpio_pin_set_dt(&cs_spec, 0);
 }
 
+/**
+ * @brief 硬件复位 ADS1256（通过 RESET 引脚），等待复位后自校准完成。
+ *
+ * @retval 0 芯片完成复位并重新进入可通信状态。
+ * @retval -ETIMEDOUT 复位后等待 DRDY 超时，芯片未按预期响应。
+ */
 int ads1256_hwreset(void) {
     /* reset_spec 配了 GPIO_ACTIVE_LOW：逻辑 1 = 物理 LOW = 断言复位 */
     gpio_pin_set_dt(&reset_spec, 1);
@@ -109,6 +146,11 @@ int ads1256_hwreset(void) {
     return ads1256_wait_drdy(500);
 }
 
+/**
+ * @brief 读取当前 24 位转换结果，符号扩展为 int32_t。
+ *
+ * @return 当前 ADC 转换原始值。
+ */
 int32_t ads1256_read_data(void) {
     uint8_t cmd       = CMD_RDATA;
     uint8_t rx_buf[3] = { 0 };
@@ -127,6 +169,14 @@ int32_t ads1256_read_data(void) {
     return -val;
 }
 
+/**
+ * @brief 初始化 ADS1256：配置 GPIO/SPI，复位芯片，写入寄存器，自校准。
+ *
+ * @retval 0 初始化成功，芯片参数已经写入并校验通过。
+ * @retval -ENODEV SPI 控制器未就绪，无法访问 ADS1256。
+ * @retval -ETIMEDOUT 复位或校准等待阶段未收到芯片响应。
+ * @retval -EIO 寄存器回读校验失败，SPI 通信结果不可信。
+ */
 int ads1256_init(void) {
     /* GPIO */
     gpio_pin_configure_dt(&cs_spec, GPIO_OUTPUT_INACTIVE);

src/ble_transport.c

@@ -38,14 +38,26 @@ static float spotter_threshold;
 static bool spotter_enabled;
 static int64_t last_heartbeat_ms;
 
-void ble_transport_adv_start(void) {
-    bt_le_adv_start(BT_LE_ADV_CONN_FAST_2, ad, ARRAY_SIZE(ad), sd, ARRAY_SIZE(sd));
-}
-
+/**
+ * @brief 延时广播任务处理函数，用于断链后重新进入可连接状态。
+ *
+ * @param work Zephyr delayable work 入口参数，当前实现未直接使用。
+ *
+ * @return 无返回值。
+ */
 static void adv_work_handler(struct k_work *work) {
+    ARG_UNUSED(work);
     ble_transport_adv_start();
 }
 
+/**
+ * @brief 蓝牙连接建立回调，接管当前连接并更新连接参数。
+ *
+ * @param conn 新建立的连接对象。
+ * @param err 连接建立阶段的状态码；非 0 表示本次连接失败。
+ *
+ * @return 无返回值。
+ */
 static void connected(struct bt_conn *conn, uint8_t err) {
     if (err) return;
 
@@ -58,7 +70,17 @@ static void connected(struct bt_conn *conn, uint8_t err) {
     bt_conn_le_param_update(conn, &param);
 }
 
+/**
+ * @brief 蓝牙断开回调，释放连接引用并安排后续重启广播。
+ *
+ * @param conn 已断开的连接对象。
+ * @param reason 协议栈给出的断开原因码。
+ *
+ * @return 无返回值。
+ */
 static void disconnected(struct bt_conn *conn, uint8_t reason) {
+    ARG_UNUSED(conn);
+    ARG_UNUSED(reason);
     if (current_conn) {
         bt_conn_unref(current_conn);
         current_conn = NULL;
@@ -69,11 +91,28 @@ static void disconnected(struct bt_conn *conn, uint8_t reason) {
     k_work_schedule(&adv_work, K_MSEC(1000));
 }
 
+/**
+ * @brief NUS 通知状态回调，用于同步记录对端是否已开启通知。
+ *
+ * @param status 当前 NUS 发送通道的可用状态。
+ *
+ * @return 无返回值。
+ */
 static void nus_send_enabled(enum bt_nus_send_status status) {
     nus_notification_enabled = (status == BT_NUS_SEND_STATUS_ENABLED);
 }
 
+/**
+ * @brief 处理来自中央设备的下行协议帧，并更新本地参数缓存。
+ *
+ * @param conn 当前接收数据的蓝牙连接对象，当前实现未直接使用。
+ * @param data 下行字节流起始地址。
+ * @param len 本次收到的字节数。
+ *
+ * @return 无返回值。
+ */
 static void nus_received_cb(struct bt_conn *conn, const uint8_t *data, uint16_t len) {
+    ARG_UNUSED(conn);
     if (len < 3 || data[0] != PROTO_SYNC0 || data[1] != PROTO_SYNC1) return;
 
     switch (data[2]) {
@@ -130,6 +169,12 @@ static struct bt_nus_cb nus_cb = {
 };
 BT_CONN_CB_DEFINE(conn_callbacks) = { .connected = connected, .disconnected = disconnected };
 
+/**
+ * @brief 初始化 BLE 协议栈、NUS 服务和内部状态。
+ *
+ * @retval 0 BLE 协议栈和 NUS 服务初始化成功。
+ * @retval 负值 Zephyr 蓝牙或 NUS 初始化阶段返回的具体错误码。
+ */
 int ble_transport_init(void) {
     k_work_init_delayable(&adv_work, adv_work_handler);
 
@@ -151,6 +196,23 @@ int ble_transport_init(void) {
     return 0;
 }
 
+/**
+ * @brief 启动 BLE 广播。
+ *
+ * @return 无返回值。
+ */
+void ble_transport_adv_start(void) {
+    bt_le_adv_start(BT_LE_ADV_CONN_FAST_2, ad, ARRAY_SIZE(ad), sd, ARRAY_SIZE(sd));
+}
+
+/**
+ * @brief 通过 NUS 发送二进制帧，自动重试最多 3 次。
+ *
+ * @param data 待发送字节缓冲区。
+ * @param len 字节数。
+ *
+ * @return 无返回值。
+ */
 void ble_transport_send(const uint8_t *data, uint16_t len) {
     if (!nus_notification_enabled || !current_conn) return;
 
@@ -161,30 +223,67 @@ void ble_transport_send(const uint8_t *data, uint16_t len) {
     }
 }
 
+/**
+ * @brief 检查是否已连接且通知已使能。
+ *
+ * @retval true 当前可以通过 NUS 对外发送数据。
+ * @retval false 当前未连接或对端尚未开启通知。
+ */
 bool ble_transport_is_ready(void) {
     return nus_notification_enabled && (current_conn != NULL);
 }
 
+/**
+ * @brief 获取最近一次下发的阻力刚度参数 K。
+ *
+ * @return 当前缓存的阻力刚度参数 K。
+ */
 float ble_transport_get_resistance_K(void) {
     return resistance_K;
 }
 
+/**
+ * @brief 获取最近一次下发的阻力阻尼参数 B。
+ *
+ * @return 当前缓存的阻力阻尼参数 B。
+ */
 float ble_transport_get_resistance_B(void) {
     return resistance_B;
 }
 
+/**
+ * @brief 获取最近一次下发的阻力时间常数 Tau。
+ *
+ * @return 当前缓存的阻力时间常数 Tau。
+ */
 float ble_transport_get_resistance_Tau(void) {
     return resistance_Tau;
 }
 
+/**
+ * @brief 获取最近一次下发的 Spotter 保护阈值。
+ *
+ * @return 当前缓存的 Spotter 阈值。
+ */
 float ble_transport_get_spotter_threshold(void) {
     return spotter_threshold;
 }
 
+/**
+ * @brief 获取最近一次下发的 Spotter 开关状态。
+ *
+ * @retval true Spotter 保护当前处于启用状态。
+ * @retval false Spotter 保护当前处于关闭状态。
+ */
 bool ble_transport_get_spotter_enabled(void) {
     return spotter_enabled;
 }
 
+/**
+ * @brief 获取最近一次收到心跳包的系统时间戳。
+ *
+ * @return 最近一次收到心跳包时的 uptime 毫秒值。
+ */
 int64_t ble_transport_get_last_heartbeat_ms(void) {
     return last_heartbeat_ms;
 }

src/button.c

@@ -20,6 +20,13 @@ static struct k_work_delayable led_off_work;
 static struct k_work tare_work;
 static volatile int blink_remaining;
 
+/**
+ * @brief 处理 LED 延时翻转，完成一次按键反馈闪烁序列。
+ *
+ * @param work Zephyr delayable work 入口参数，当前实现未直接使用。
+ *
+ * @return 无返回值。
+ */
 static void led_off_handler(struct k_work *work) {
     if (blink_remaining <= 0) return;
 
@@ -31,6 +38,13 @@ static void led_off_handler(struct k_work *work) {
     }
 }
 
+/**
+ * @brief 在工作队列上下文执行去皮，并启动 LED 闪烁反馈。
+ *
+ * @param work Zephyr work 入口参数，当前实现未直接使用。
+ *
+ * @return 无返回值。
+ */
 static void tare_work_handler(struct k_work *work) {
     LOG_INF("Button1 pressed → tare");
     sensor_perform_tare();
@@ -41,10 +55,29 @@ static void tare_work_handler(struct k_work *work) {
     k_work_schedule(&led_off_work, K_MSEC(LED_FLASH_MS));
 }
 
+/**
+ * @brief 按键 GPIO 中断回调，只负责把去皮请求转交到工作队列。
+ *
+ * @param dev 触发中断的 GPIO 设备，当前实现未直接使用。
+ * @param cb GPIO 回调对象，当前实现未直接使用。
+ * @param pins 本次触发的引脚位图，当前实现未直接使用。
+ *
+ * @return 无返回值。
+ */
 static void btn1_isr(const struct device *dev, struct gpio_callback *cb, uint32_t pins) {
+    ARG_UNUSED(dev);
+    ARG_UNUSED(cb);
+    ARG_UNUSED(pins);
     k_work_submit(&tare_work);
 }
 
+/**
+ * @brief 初始化按键模块：Button1 按下触发去皮 + LED1 闪烁反馈。
+ *
+ * @retval 0 按键中断、去皮 work 和 LED 反馈均初始化成功。
+ * @retval -ENODEV 按键或 LED 对应的 GPIO 设备未就绪。
+ * @retval 负值 GPIO 配置、中断配置或回调注册阶段返回的具体错误码。
+ */
 int button_init(void) {
     if (!gpio_is_ready_dt(&btn1) || !gpio_is_ready_dt(&led1)) {
         LOG_ERR("GPIO device not ready");

src/main.c

@@ -16,6 +16,12 @@
 
 LOG_MODULE_REGISTER(main, LOG_LEVEL_INF);
 
+/**
+ * @brief 初始化系统各模块并进入主线程驻留状态。
+ *
+ * @retval 0 理论上的正常返回值；当前实现进入永久休眠后不会主动返回。
+ * @retval -1 按键模块或传感器模块初始化失败。
+ */
 int main(void) {
     k_msleep(2000);
     LOG_INF("--- GML670 System (CoP Binary Protocol) ---");

src/sensor.c

@@ -222,12 +222,12 @@ static void sensor_thread_fn(void *p1, void *p2, void *p3) {
 }
 
 /**
- * @brief 初始化传感器采集链路并启动后台采集线程。
+ * @brief 初始化压力传感器模块：ADS1256 硬件 + 初始去皮 + 创建采集线程。
  *
- * @param 无。
+ * 调用后采集线程自动启动，以 50 Hz 循环采集、计算 CoP 并发送 BLE 数据。
  *
  * @retval 0 初始化成功，传感器线程已经启动并完成一次初始去皮。
- * @retval 负值或其他错误码 ADS1256 初始化失败
+ * @retval 负值 ADS1256 初始化阶段返回的具体错误码。
  */
 int sensor_init(void) {
     int err = ads1256_init();
@@ -253,9 +253,7 @@ int sensor_init(void) {
 }
 
 /**
- * @brief 请求后台线程在下一帧边界执行去皮。
- *
- * @param 无。
+ * @brief 执行四路去皮（零点校准），可从任意线程调用。
  *
  * @return 无返回值。
  */