chore: 更新 .gitignore 文件

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

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__