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

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);