FIX: 修复CI静态分析误通过、API缺陷及文档错误

.github/workflows/stable-ci.yml

@@ -117,8 +117,8 @@ jobs:
     - name: 运行基础静态分析
       run: |
         # 只检查严重错误，忽略风格问题
-        cppcheck --enable=error,warning \
+        cppcheck --enable=warning \
           --error-exitcode=1 \
           --suppress=missingIncludeSystem \
           --suppress=missingInclude \
-          bits_button.c bits_button.h || echo "静态分析完成，发现一些风格问题但不影响功能"
+          bits_button.c bits_button.h

bits_button.c

@@ -249,7 +249,7 @@ static uint8_t bits_btn_peek_buffer_c11(bits_btn_result_t *result)
     return true;
 }
 
-const bits_btn_buffer_ops_t c11_buffer_ops = {
+static const bits_btn_buffer_ops_t c11_buffer_ops = {
     .init = bits_btn_init_buffer_c11,
     .write = bits_btn_write_buffer_overwrite_c11,
     .read = bits_btn_read_buffer_c11,
@@ -271,10 +271,7 @@ static bits_btn_result_user_filter_callback bits_btn_result_user_filter_cb = NUL
 
 void bits_btn_register_result_filter_callback(bits_btn_result_user_filter_callback cb)
 {
-    if(cb != NULL)
-    {
-        bits_btn_result_user_filter_cb = cb;
-    }
+    bits_btn_result_user_filter_cb = cb;
 }
 #endif
 

docs/api.md

@@ -167,6 +167,7 @@ typedef struct button_obj_t {
     state_bits_type_t state_bits;                       // 状态位图
     const bits_btn_obj_param_t *param;                  // 参数指针
 } button_obj_t;
+```
 
 ### 按键对象参数结构
 

docs/testing.md

@@ -99,11 +99,10 @@ int main(void) {
 测试配置文件位于`test/config/test_config.h`，包含以下参数：
 
 ```c
-#define MAX_TEST_EVENTS 100        // 最大测试事件数
-#define TEST_TIMEOUT_MS 5000       // 测试超时时间
-#define DEBOUNCE_TIME_MS 20        // 消抖时间
-#define LONG_PRESS_TIME_MS 1000    // 长按时间
-#define DOUBLE_CLICK_TIME_MS 300   // 双击时间窗口
+#define MAX_CAPTURED_EVENTS           100    // 最大捕获事件数
+#define TEST_DEBOUNCE_TIME_MS         BITS_BTN_DEBOUNCE_TIME_MS       // 消抖时间 (默认40ms)
+#define TEST_LONG_PRESS_TIME_MS       BITS_BTN_LONG_PRESS_START_TIME_MS // 长按开始时间 (默认1000ms)
+#define TEST_TIME_WINDOW_MS           BITS_BTN_TIME_WINDOW_TIME_MS    // 多击时间窗口 (默认300ms)
 ```
 
 ## 测试工具

examples/example_callback.c

@@ -1,5 +1,6 @@
 // 1. 包含头文件
 #include "bits_button.h"
+#include <stdarg.h>
 
 typedef enum
 {

examples/example_poll.c

@@ -1,5 +1,6 @@
 // 1. 包含头文件
 #include "bits_button.h"
+#include <stdarg.h>
 
 typedef enum
 {

simulator/ButtonSimulator.md

@@ -9,21 +9,16 @@
 simulator/
 ├── adapter_layer/           # C语言适配层
 │   ├── button_adapter.c     # 适配层实现（连接C库和Python模拟器）
-│   ├── button_adapter.h     # 适配层接口定义
-│   ├── button_types.h       # 按键类型定义
-│   └── Makefile             # 编译配置
+│   └── button_adapter.h     # 适配层接口定义
 ├── python_simulator/        # Python实现的模拟器
 │   ├── advanced_v2_sim.py   # 高级模拟器实现
-│   ├── button_ctrl.py       # 按键控制逻辑
-│   ├── button_ui.py         # 用户界面实现
-│   ├── event_logger.py      # 事件日志记录
-│   └── config_manager.py    # 配置管理
+│   └── button_ctrl.py      # 按键控制逻辑
 ├── key_bindings.json        # 按键绑定配置文件
 ├── run.py                   # 主运行脚本
 ├── output/                  # 编译输出目录
-│   ├── libbutton.dll        # Windows动态库
-│   ├── libbutton.so         # Linux动态库
-│   └── libbutton.dylib      # macOS动态库
+│   ├── button.dll           # Windows动态库
+│   ├── button.so            # Linux动态库
+│   └── button.dylib         # macOS动态库
 └── ButtonSimulator.md       # 本文档
 ```
 

test/README.md

@@ -46,7 +46,7 @@ test/
 ### 基础功能测试 (7个)
 1. **test_single_click_event** - 单击事件测试
 2. **test_double_click_event** - 双击事件测试
-3. **test_triple_click_event** - 快速双击测试
+3. **test_fast_double_click_event** - 快速双击测试
 4. **test_long_press_event** - 长按事件测试
 5. **test_long_press_hold_event** - 长按保持测试
 6. **test_state_reset_functionality** - 按键状态重置功能测试
@@ -170,11 +170,10 @@ make
 
 ### 测试配置 (test/config/test_config.h)
 ```c
-#define MAX_TEST_EVENTS 100        // 最大测试事件数
-#define TEST_TIMEOUT_MS 5000       // 测试超时时间
-#define DEBOUNCE_TIME_MS 20        // 消抖时间
-#define LONG_PRESS_TIME_MS 1000    // 长按时间
-#define DOUBLE_CLICK_TIME_MS 300   // 双击时间窗口
+#define MAX_CAPTURED_EVENTS           100    // 最大捕获事件数
+#define TEST_DEBOUNCE_TIME_MS         BITS_BTN_DEBOUNCE_TIME_MS       // 消抖时间 (默认40ms)
+#define TEST_LONG_PRESS_TIME_MS       BITS_BTN_LONG_PRESS_START_TIME_MS // 长按开始时间 (默认1000ms)
+#define TEST_TIME_WINDOW_MS           BITS_BTN_TIME_WINDOW_TIME_MS    // 多击时间窗口 (默认300ms)
 ```
 
 ## 测试工具

test/cases/basic/test_initialization.c

@@ -123,28 +123,7 @@ void test_custom_parameters(void) {
     int event_count = test_framework_get_event_count();
 
     if (event_count == 0) {
-        printf("注意: 自定义参数可能需要调整，使用默认参数测试\n");
-
-        // 清空并重新测试使用默认参数
-        test_framework_clear_events();
-        static const bits_btn_obj_param_t default_param = TEST_DEFAULT_PARAM();
-        button_obj_t default_button = BITS_BUTTON_INIT(1, 1, &default_param);
-
-        bits_btn_config_t def_config = {
-            .btns = &default_button,
-            .btns_cnt = 1,
-            .read_button_level_func = test_framework_mock_read_button,
-            .bits_btn_result_cb = test_framework_event_callback,
-            .bits_btn_debug_printf = test_framework_log_printf
-        };
-        bits_button_init(&def_config);
-
-        mock_button_click(1, STANDARD_CLICK_TIME_MS);
-        time_simulate_time_window_end();
-
-        ASSERT_EVENT_EXISTS(1, BTN_EVENT_FINISH);
-        printf("自定义参数测试通过: 默认参数正常工作\n");
-        return;
+        TEST_IGNORE_MESSAGE("自定义参数未产生事件，使用默认参数测试跳过此验证");
     }
 
     // 应该是单击

test/cases/basic/test_single_operations.c

@@ -23,11 +23,11 @@ void basic_tearDown(void) {
 
 void test_single_click_event(void) {
     printf("\n=== 测试单击事件 ===\n");
-    
+
     // 创建按键对象
     static const bits_btn_obj_param_t param = TEST_DEFAULT_PARAM();
     button_obj_t button = BITS_BUTTON_INIT(1, 1, &param);
-    
+
     bits_btn_config_t config = {
         .btns = &button,
         .btns_cnt = 1,
@@ -50,11 +50,11 @@ void test_single_click_event(void) {
 
 void test_double_click_event(void) {
     printf("\n=== 测试双击事件 ===\n");
-    
+
     // 创建按键对象
     static const bits_btn_obj_param_t param = TEST_DEFAULT_PARAM();
     button_obj_t button = BITS_BUTTON_INIT(1, 1, &param);
-    
+
     bits_btn_config_t config = {
         .btns = &button,
         .btns_cnt = 1,
@@ -73,15 +73,15 @@ void test_double_click_event(void) {
     printf("双击测试通过\n");
 }
 
-// ==================== 三连击测试 ====================
+// ==================== 快速双击测试 ====================
 
-void test_triple_click_event(void) {
+void test_fast_double_click_event(void) {
     printf("\n=== 测试双击事件(快速) ===\n");
-    
+
     // 创建按键对象
     static const bits_btn_obj_param_t param = TEST_DEFAULT_PARAM();
     button_obj_t button = BITS_BUTTON_INIT(1, 1, &param);
-    
+
     bits_btn_config_t config = {
         .btns = &button,
         .btns_cnt = 1,
@@ -91,7 +91,7 @@ void test_triple_click_event(void) {
     };
     bits_button_init(&config);
 
-    // 模拟快速双击（库不支持三连击，所以测试双击）
+    // 模拟快速双击
     mock_multiple_clicks(1, 2, STANDARD_CLICK_TIME_MS, 150);
     time_simulate_time_window_end();
 
@@ -104,11 +104,11 @@ void test_triple_click_event(void) {
 
 void test_long_press_event(void) {
     printf("\n=== 测试长按事件 ===\n");
-    
+
     // 创建按键对象
     static const bits_btn_obj_param_t param = TEST_DEFAULT_PARAM();
     button_obj_t button = BITS_BUTTON_INIT(1, 1, &param);
-    
+
     bits_btn_config_t config = {
         .btns = &button,
         .btns_cnt = 1,
@@ -135,16 +135,16 @@ void test_long_press_event(void) {
 
 void test_long_press_hold_event(void) {
     printf("\n=== 测试长按保持事件 ===\n");
-    
+
     // 创建按键对象，设置较短的长按周期
     static const bits_btn_obj_param_t param = {
         .long_press_period_trigger_ms = 500,
         .long_press_start_time_ms = BITS_BTN_LONG_PRESS_START_TIME_MS,
         .time_window_time_ms = BITS_BTN_TIME_WINDOW_TIME_MS
     };
-    
+
     button_obj_t button = BITS_BUTTON_INIT(1, 1, &param);
-    
+
     bits_btn_config_t config = {
         .btns = &button,
         .btns_cnt = 1,

test/cases/edge/test_state_machine_edge.c

@@ -130,9 +130,7 @@ void test_long_press_period_boundary(void) {
 
     // 如果没有长按保持事件，说明这个功能可能没有实现或有问题
     if (hold_count == 0) {
-        printf("注意: 长按周期功能可能未完全实现，跳过此测试\n");
-        printf("长按周期边界测试通过: 基本长按功能正常\n");
-        return;
+        TEST_IGNORE_MESSAGE("长按周期功能未触发保持事件，跳过此验证");
     }
 
     ASSERT_LONG_PRESS_COUNT(1, 1);

test/test_main_new.c

@@ -9,7 +9,7 @@
 // 基础功能测试
 extern void test_single_click_event(void);
 extern void test_double_click_event(void);
-extern void test_triple_click_event(void);
+extern void test_fast_double_click_event(void);
 extern void test_long_press_event(void);
 extern void test_long_press_hold_event(void);
 extern void test_state_reset_functionality(void);
@@ -113,7 +113,7 @@ int main(void) {
     printf("【单按键基础功能测试】\n");
     RUN_TEST(test_single_click_event);
     RUN_TEST(test_double_click_event);
-    RUN_TEST(test_triple_click_event);
+    RUN_TEST(test_fast_double_click_event);
     RUN_TEST(test_long_press_event);
     RUN_TEST(test_long_press_hold_event);
     RUN_TEST(test_state_reset_functionality);