chore: 更新 .gitignore 文件

- 添加 docs 文件夹到忽略列表，以忽略 Doxygen 生成的文件
- 保持原有的忽略规则不变

lib/utils/ds/hashtable.c

@@ -52,7 +52,7 @@ static void adjust_capacity(hash_table_t* ht, int new_cap) {
     new_cap = next_power_of_two(new_cap);
     Assert(new_cap >= ht->entries.cap);
 
-    vector_header(old_entries, hash_entry_t);
+    VECTOR_HEADER(old_entries, hash_entry_t);
     old_entries.data = ht->entries.data;
     old_entries.cap = ht->entries.cap;
 

lib/utils/ds/hashtable.h

@@ -1,3 +1,10 @@
+/**
+ * @file hashtable.h
+ * @brief 开放寻址法哈希表实现
+ * 
+ * 提供基于向量容器的哈希表实现，支持动态扩容和墓碑机制
+ */
+
 #ifndef __SMCC_HASHTABLE_H__
 #define __SMCC_HASHTABLE_H__
 
@@ -5,39 +12,113 @@
 #include <lib/rt/rt_alloc.h>
 #include "vector.h"
 
-// 哈希表条目状态标记
+/**
+ * @enum ht_entry_state_t
+ * @brief 哈希表条目状态标识
+ */
 typedef enum hash_table_entry_state {
-    ENTRY_EMPTY,
-    ENTRY_ACTIVE,
-    ENTRY_TOMBSTONE
+    ENTRY_EMPTY,    /**< 空槽位（从未使用过） */
+    ENTRY_ACTIVE,   /**< 有效条目（包含键值对） */
+    ENTRY_TOMBSTONE /**< 墓碑标记（已删除条目） */
 } ht_entry_state_t;
 
-// 哈希表条目结构（不管理key/value内存）
+/**
+ * @struct hash_entry_t
+ * @brief 哈希表条目结构
+ * 
+ * @note key/value内存由调用者管理，哈希表不负责其生命周期
+ */
 typedef struct hash_entry {
-    const void* key;        // 由调用者管理
-    void* value;            // 由调用者管理
-    u32_t hash;            // 预计算哈希值
-    ht_entry_state_t state;    // 条目状态
+    const void* key;        /**< 键指针（不可变） */
+    void* value;            /**< 值指针 */
+    u32_t hash;            /**< 预计算的哈希值（避免重复计算） */
+    ht_entry_state_t state; /**< 当前条目状态 */
 } hash_entry_t;
 
-// 哈希表主体结构
+/**
+ * @struct hash_table_t
+ * @brief 哈希表主体结构
+ * 
+ * 使用开放寻址法实现，采用墓碑标记处理删除操作
+ */
 typedef struct hash_table {
-    vector_header(entries, hash_entry_t);  // 使用vector管理条目
-    u32_t count;           // 有效条目数（不含墓碑）
-    u32_t tombstone_count; // 墓碑数量
+    VECTOR_HEADER(entries, hash_entry_t);  /**< 条目存储容器 */
+    u32_t count;           /**< 有效条目数量（不含墓碑） */
+    u32_t tombstone_count; /**< 墓碑条目数量 */
+    /**
+     * @brief 哈希函数指针
+     * @param key 键指针
+     * @return 32位无符号哈希值
+     */
     u32_t (*hash_func)(const void* key);
+    /**
+     * @brief 键比较函数指针
+     * @param key1 第一个键指针
+     * @param key2 第二个键指针
+     * @return 相同返回0，不同返回非0
+     */
     int(*key_cmp)(const void* key1, const void* key2);
 } hash_table_t;
 
-// WARN you need set hash_func and key_cmp before use
-void init_hashtable(hash_table_t* ht) ;
+/**
+ * @brief 初始化哈希表结构
+ * @param ht 哈希表实例指针
+ * 
+ * @warning 必须设置hash_func和key_cmp后才能使用
+ */
+void init_hashtable(hash_table_t* ht);
 
+/**
+ * @brief 插入/更新键值对
+ * @param ht 哈希表实例指针
+ * @param key 键指针
+ * @param value 值指针
+ * @return 被替换的旧值指针（无替换返回NULL）
+ */
 void* hashtable_set(hash_table_t* ht, const void* key, void* value);
+
+/**
+ * @brief 查找键对应值
+ * @param ht 哈希表实例指针
+ * @param key 查找键指针
+ * @return 找到返回值指针，未找到返回NULL
+ */
 void* hashtable_get(hash_table_t* ht, const void* key);
+
+/**
+ * @brief 删除键值对
+ * @param ht 哈希表实例指针
+ * @param key 要删除的键指针
+ * @return 被删除的值指针（不存在返回NULL）
+ * 
+ * @note 实际采用墓碑标记方式删除
+ */
 void* hashtable_del(hash_table_t* ht, const void* key);
+
+/**
+ * @brief 销毁哈希表
+ * @param ht 哈希表实例指针
+ * 
+ * @note 仅释放哈希表内部内存，不会释放key/value内存
+ */
 void hashtable_destory(hash_table_t* ht);
 
+/**
+ * @typedef hash_table_iter_func
+ * @brief 哈希表迭代回调函数类型
+ * @param key 当前键指针
+ * @param value 当前值指针
+ * @param context 用户上下文指针
+ * @return 返回非0停止迭代
+ */
 typedef int (*hash_table_iter_func)(const void* key, void* value, void* context);
+
+/**
+ * @brief 遍历哈希表所有有效条目
+ * @param ht 哈希表实例指针
+ * @param iter_func 迭代回调函数
+ * @param context 用户上下文指针
+ */
 void hashtable_foreach(hash_table_t* ht, hash_table_iter_func iter_func, void* context);
 
 #endif // __SMCC_HASHTABLE_H__

lib/utils/ds/vector.h

@@ -1,17 +1,44 @@
-// vector.h
+/**
+ * @file vector.h
+ * @brief 动态数组（Vector）实现
+ * 
+ * 提供类型安全的动态数组容器实现，支持自动扩容和基本操作
+ */
+
 #ifndef __SMCC_DS_VECTOR_H__
 #define __SMCC_DS_VECTOR_H__
 
 #include <lib/rt/rt.h>
 
-#define vector_header(name, type) \
-    struct { \
-        rt_size_t size; \
-        rt_size_t cap; \
-        type *data; \
-    } name \
+/** @defgroup vector_struct 数据结构定义 */
 
-// You can't malloc at init function becase some user just need a header
+/**
+ * @def VECTOR_HEADER(name, type)
+ * @brief 声明向量结构体
+ * @param name 结构体变量名
+ * @param type 存储的数据类型
+ * 
+ * 生成包含size/cap/data三个字段的结构体定义：
+ * - size: 当前元素数量
+ * - cap: 数组容量
+ * - data: 存储数组指针
+ */
+#define VECTOR_HEADER(name, type) \
+    struct { \
+        rt_size_t size;   /**< 当前元素数量 */ \
+        rt_size_t cap;    /**< 数组容量 */ \
+        type *data;       /**< 数据存储指针 */ \
+    } name
+
+/** @defgroup vector_operations 向量操作宏 */
+
+/**
+ * @def vector_init(vec)
+ * @brief 初始化向量结构体
+ * @param vec 要初始化的向量结构体变量
+ * 
+ * @note 此宏不会分配内存，仅做零初始化
+ */
 #define vector_init(vec) \
     do { \
         (vec).size = 0, \
@@ -19,6 +46,15 @@
         (vec).data = 0; \
     } while(0)
 
+/**
+ * @def vector_push(vec, value)
+ * @brief 添加元素到向量末尾
+ * @param vec 目标向量结构体
+ * @param value 要添加的值（需匹配存储类型）
+ * 
+ * @note 当容量不足时自动扩容为2倍（初始容量为8）
+ * @warning 内存分配失败时会触发LOG_FATAL
+ */
 #define vector_push(vec, value) \
     do { \
         if (vec.size >= vec.cap) { \
@@ -33,15 +69,43 @@
         (vec).data[(vec).size++] = value; \
     } while(0)
 
+/**
+ * @def vector_pop(vec)
+ * @brief 弹出最后一个元素
+ * @param vec 目标向量结构体
+ * @return 最后元素的引用
+ * @warning 需确保size > 0时使用
+ */
 #define vector_pop(vec) \
     ((vec).data[--(vec).size])
 
+/**
+ * @def vector_at(vec, idx)
+ * @brief 获取指定索引元素
+ * @param vec 目标向量结构体
+ * @param idx 元素索引（0 <= idx < size）
+ * @return 对应元素的引用
+ */
 #define vector_at(vec, idx) \
     (((vec).data)[idx])
 
+/**
+ * @def vector_idx(vec, ptr)
+ * @brief 获取元素指针对应的索引
+ * @param vec 目标向量结构体
+ * @param ptr 元素指针（需在data数组范围内）
+ * @return 元素索引值
+ */
 #define vector_idx(vec, ptr) \
     ((ptr) - (vec).data)
 
+/**
+ * @def vector_free(vec)
+ * @brief 释放向量内存
+ * @param vec 目标向量结构体
+ * 
+ * @note 释放后需重新初始化才能再次使用
+ */
 #define vector_free(vec) \
     do { \
         salloc_free((vec).data); \
@@ -49,4 +113,4 @@
         (vec).size = (vec).cap = 0; \
     } while(0)
 
-#endif
+#endif // __SMCC_DS_VECTOR_H__

lib/utils/strpool/strpool.h

@@ -1,3 +1,10 @@
+/**
+ * @file strpool.h
+ * @brief 字符串池实现
+ * 
+ * 提供字符串驻留（String Interning）功能，保证相同字符串的唯一性存储
+ */
+
 #ifndef __SMCC_STRPOOL_H__
 #define __SMCC_STRPOOL_H__
 
@@ -5,13 +12,43 @@
 #include <lib/rt/rt_alloc.h>
 #include <lib/utils/ds/hashtable.h>
 
+/**
+ * @struct strpool_t
+ * @brief 字符串池上下文
+ * 
+ * 组合哈希表和专用内存分配器实现的高效字符串存储池
+ */
 typedef struct strpool {
-    hash_table_t ht;       // 用于快速查找字符串
-    long_alloc_t stralloc; // 专门用于字符串存储的分配器
+    hash_table_t ht;       /**< 哈希表用于快速查找已存储字符串 */
+    long_alloc_t stralloc; /**< 长块分配器优化小字符串内存管理 */
 } strpool_t;
 
+/**
+ * @brief 初始化字符串池
+ * @param pool 字符串池实例指针
+ * 
+ * @warning 使用前需确保 hashtable 的 hash_func 和 key_cmp 已正确设置
+ */
 void init_strpool(strpool_t* pool);
+
+/**
+ * @brief 驻留字符串到池中
+ * @param pool 字符串池实例指针
+ * @param str 要驻留的 C 字符串
+ * @return 池中唯一字符串的持久指针
+ * 
+ * @note 返回值生命周期与字符串池一致
+ * @note 重复插入相同字符串会返回已有指针
+ */
 const char* strpool_intern(strpool_t* pool, const char* str);
+
+/**
+ * @brief 销毁字符串池
+ * @param pool 字符串池实例指针
+ * 
+ * @warning 销毁后已获取的字符串指针将失效
+ * @note 会自动释放所有驻留字符串内存
+ */
 void strpool_destroy(strpool_t* pool);
 
 #endif // __SMCC_STRPOOL_H__