chore: 更新 .gitignore 文件

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

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__