docs: update math API docs

docs/api/math/vector4/constructor.md

@@ -0,0 +1,25 @@
+# Vector4::Vector4
+
+使用四个分量构造四维向量。
+
+```cpp
+constexpr Vector4(float x, float y, float z, float w)
+```
+
+**参数：**
+- `x` - X 分量
+- `y` - Y 分量
+- `z` - Z 分量
+- `w` - W 分量（通常用于齐次坐标）
+
+**返回：** 新创建的 Vector4 实例
+
+**示例：**
+
+```cpp
+Vector4 v(1.0f, 2.0f, 3.0f, 4.0f);
+```
+
+## 相关文档
+
+- [Vector4 总览](vector4.md) - 返回类总览

docs/api/math/vector4/constructor_default.md

@@ -0,0 +1,20 @@
+# Vector4::Vector4
+
+```cpp
+Vector4() = default;
+```
+
+默认构造函数，创建零向量 (0, 0, 0, 0)。
+
+**返回：** 新创建的 Vector4 实例
+
+**示例：**
+
+```cpp
+Vector4 v;  // (0, 0, 0, 0)
+```
+
+## 相关文档
+
+- [Vector4 总览](vector4.md) - 返回类总览
+- [Zero](zero.md) - 返回零向量

docs/api/math/vector4/constructor_vector3.md

@@ -0,0 +1,25 @@
+# Vector4::Vector4 (from Vector3)
+
+```cpp
+explicit Vector4(const Vector3& v, float w = 0.0f)
+```
+
+从 Vector3 构造四维向量，w 分量默认为 0.0f。
+
+**参数：**
+- `v` - 源 Vector3 向量
+- `w` - W 分量（默认值为 `0.0f`）
+
+**返回：** 新创建的 Vector4 实例
+
+**示例：**
+
+```cpp
+Vector3 v3(1.0f, 2.0f, 3.0f);
+Vector4 v4a(v3);
+Vector4 v4b(v3, 1.0f);
+```
+
+## 相关文档
+
+- [Vector4 总览](vector4.md) - 返回类总览

docs/api/math/vector4/dot.md

@@ -1,11 +1,11 @@
 # Vector4::Dot
 
+计算两个 4D 向量的点积。
+
 ```cpp
 static float Dot(const Vector4& a, const Vector4& b)
 ```
 
-计算两个 4D 向量的点积。
-
 **参数：**
 - `a` - 第一个向量
 - `b` - 第二个向量
@@ -21,3 +21,7 @@ Vector4 a(1.0f, 2.0f, 3.0f, 4.0f);
 Vector4 b(4.0f, 3.0f, 2.0f, 1.0f);
 float dot = Vector4::Dot(a, b);  // 20.0f
 ```
+
+## 相关文档
+
+- [Vector4 总览](vector4.md)

docs/api/math/vector4/one.md

@@ -1,11 +1,11 @@
 # Vector4::One
 
+返回单位向量 (1, 1, 1, 1)。
+
 ```cpp
 static Vector4 One()
 ```
 
-返回单位向量 (1, 1, 1, 1)。
-
 **返回：** `Vector4` - 值为 (1, 1, 1, 1) 的向量
 
 **复杂度：** O(1)
@@ -15,3 +15,7 @@ static Vector4 One()
 ```cpp
 Vector4 unit = Vector4::One();
 ```
+
+## 相关文档
+
+- [Vector4 总览](vector4.md)

docs/api/math/vector4/operator-add.md

@@ -0,0 +1,24 @@
+# Vector4::operator+
+
+```cpp
+Vector4 operator+(const Vector4& other) const
+```
+
+向量加法。
+
+**参数：**
+- `other` - 要相加的向量
+
+**返回：** `Vector4` - 相加结果向量
+
+**示例：**
+
+```cpp
+Vector4 a(1.0f, 2.0f, 3.0f, 4.0f);
+Vector4 b(5.0f, 6.0f, 7.0f, 8.0f);
+Vector4 c = a + b;  // (6, 8, 10, 12)
+```
+
+## 相关文档
+
+- [Vector4 总览](vector4.md) - 返回类总览

docs/api/math/vector4/operator-brackets.md

@@ -0,0 +1,28 @@
+# Vector4::operator[]
+
+```cpp
+float operator[](int index) const
+float& operator[](int index)
+```
+
+通过下标访问向量分量。
+
+**参数：**
+- `index` - 分量索引 (0=x, 1=y, 2=z, 3=w)
+
+**返回：** `float` 或 `float&` - 对应分量的值（常量版本返回值，左值版本返回引用）
+
+**注意事项：** 未进行边界检查。index 应在 [0, 3] 范围内。
+
+**示例：**
+
+```cpp
+Vector4 v(1.0f, 2.0f, 3.0f, 4.0f);
+float x = v[0];   // 1.0f
+float w = v[3];   // 4.0f
+v[1] = 5.0f;      // v 变为 (1, 5, 3, 4)
+```
+
+## 相关文档
+
+- [Vector4 总览](vector4.md) - 返回类总览

docs/api/math/vector4/operator-eq.md

@@ -0,0 +1,25 @@
+# Vector4::operator==
+
+```cpp
+bool operator==(const Vector4& other) const
+```
+
+判断两个向量是否相等。
+
+**参数：**
+- `other` - 要比较的向量
+
+**返回：** `bool` - 如果所有分量差的绝对值都小于 EPSILON 则返回 true，否则返回 false
+
+**示例：**
+
+```cpp
+Vector4 a(1.0f, 2.0f, 3.0f, 4.0f);
+Vector4 b(1.0f, 2.0f, 3.0f, 4.0f);
+bool eq = (a == b);  // true
+```
+
+## 相关文档
+
+- [Vector4 总览](vector4.md) - 返回类总览
+- [operator!=](operator-ne.md) - 不等比较

docs/api/math/vector4/operator-mul.md

@@ -0,0 +1,23 @@
+# Vector4::operator*
+
+```cpp
+Vector4 operator*(float scalar) const
+```
+
+向量与标量乘法。
+
+**参数：**
+- `scalar` - 标量值
+
+**返回：** `Vector4` - 缩放后的向量
+
+**示例：**
+
+```cpp
+Vector4 v(1.0f, 2.0f, 3.0f, 4.0f);
+Vector4 scaled = v * 2.0f;  // (2, 4, 6, 8)
+```
+
+## 相关文档
+
+- [Vector4 总览](vector4.md) - 返回类总览

docs/api/math/vector4/operator-ne.md

@@ -0,0 +1,24 @@
+# Vector4::operator!=
+
+```cpp
+bool operator!=(const Vector4& other) const
+```
+
+判断两个向量是否不相等。
+
+**参数：**
+- `other` - 要比较的向量
+
+**返回：** `bool` - 如果任何分量差的绝对值大于等于 EPSILON 则返回 true，否则返回 false
+
+**示例：**
+
+```cpp
+Vector4 a(1.0f, 2.0f, 3.0f, 4.0f);
+Vector4 b(5.0f, 6.0f, 7.0f, 8.0f);
+bool ne = (a != b);  // true
+```
+
+## 相关文档
+
+- [Vector4 总览](vector4.md) - 返回类总览

docs/api/math/vector4/operator-sub.md

@@ -0,0 +1,24 @@
+# Vector4::operator-
+
+```cpp
+Vector4 operator-(const Vector4& other) const
+```
+
+向量减法。
+
+**参数：**
+- `other` - 要相减的向量
+
+**返回：** `Vector4` - 相减结果向量
+
+**示例：**
+
+```cpp
+Vector4 a(5.0f, 6.0f, 7.0f, 8.0f);
+Vector4 b(1.0f, 2.0f, 3.0f, 4.0f);
+Vector4 c = a - b;  // (4, 4, 4, 4)
+```
+
+## 相关文档
+
+- [Vector4 总览](vector4.md) - 返回类总览

docs/api/math/vector4/project.md

@@ -1,11 +1,11 @@
 # Vector4::Project
 
+将向量投影到法线向量上。
+
 ```cpp
 static Vector4 Project(const Vector4& vector, const Vector4& onNormal)
 ```
 
-将向量投影到法线向量上。
-
 **参数：**
 - `vector` - 要投影的向量
 - `onNormal` - 投影到的法线向量
@@ -21,3 +21,7 @@ Vector4 v(1.0f, 1.0f, 1.0f, 1.0f);
 Vector4 normal(1.0f, 0.0f, 0.0f, 0.0f);
 Vector4 projected = Vector4::Project(v, normal);  // (1, 0, 0, 0)
 ```
+
+## 相关文档
+
+- [Vector4 总览](vector4.md)

docs/api/math/vector4/tovector3.md

@@ -1,11 +1,11 @@
 # Vector4::ToVector3
 
+将 Vector4 转换为 Vector3，丢弃 w 分量。
+
 ```cpp
 Vector3 ToVector3() const
 ```
 
-将 Vector4 转换为 Vector3，丢弃 w 分量。
-
 **返回：** `Vector3` - 转换后的 Vector3 (x, y, z)
 
 **复杂度：** O(1)
@@ -16,3 +16,8 @@ Vector3 ToVector3() const
 Vector4 pos4(1.0f, 2.0f, 3.0f, 1.0f);
 Vector3 pos3 = pos4.ToVector3();  // (1, 2, 3)
 ```
+
+## 相关文档
+
+- [Vector4 总览](vector4.md)
+- [Vector3 总览](../vector3/vector3.md)

docs/api/math/vector4/vector4.md

@@ -1,53 +1,71 @@
 # Vector4
 
-4D 向量结构体，用于表示齐次坐标、颜色 (RGBA) 或 SIMD 操作。
+**命名空间**: `XCEngine::Math`
 
-**头文件：** `#include <XCEngine/Math/Vector4.h>`
+**类型**: `struct`
 
-**命名空间：** `XCEngine::Math`
+**头文件**: `XCEngine/Math/Vector4.h`
 
-## 结构体定义
+**描述**: 四维向量，用于齐次坐标变换和四元数相关计算
+
+## 概述
+
+Vector4 是四维向量结构体，常用于：
+- 齐次坐标变换（x, y, z, w）
+- RGBA 颜色表示
+- SIMD 矢量操作
+- 四元数分量存储
+
+## 结构体成员
+
+| 成员 | 类型 | 描述 | 默认值 |
+|------|------|------|--------|
+| `x` | `float` | X 分量 | `0.0f` |
+| `y` | `float` | Y 分量 | `0.0f` |
+| `z` | `float` | Z 分量 | `0.0f` |
+| `w` | `float` | W 分量（齐次坐标） | `0.0f` |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [`Vector4()`](constructor_default.md) | 默认构造函数，创建零向量 |
+| [`Vector4(x, y, z, w)`](constructor.md) | 从四个分量构造向量 |
+| [`Vector4(Vector3, w)`](constructor_vector3.md) | 从 Vector3 构造（w 默认 0） |
+| [`Zero`](zero.md) | 返回零向量 (0, 0, 0, 0) |
+| [`One`](one.md) | 返回单位向量 (1, 1, 1, 1) |
+| [`Dot`](dot.md) | 计算两个向量的点积 |
+| [`Project`](project.md) | 将向量投影到法线向量上 |
+| [`ToVector3`](tovector3.md) | 转换为 Vector3 |
+| [`operator[]`](./operator-brackets.md) | 下标访问分量 |
+| [`operator+`](operator-add.md) | 向量加法 |
+| [`operator-`](operator-sub.md) | 向量减法 |
+| [`operator*`](operator-mul.md) | 向量数乘 |
+| [`operator==`](operator-eq.md) | 相等比较 |
+| [`operator!=`](operator-ne.md) | 不等比较 |
+
+## 使用示例
 
 ```cpp
-struct Vector4 {
-    float x = 0.0f;
-    float y = 0.0f;
-    float z = 0.0f;
-    float w = 0.0f;
-};
+#include <XCEngine/Math/Vector4.h>
+#include <XCEngine/Math/Vector3.h>
+#include <cstdio>
+
+int main() {
+    Vector4 a(1.0f, 2.0f, 3.0f, 4.0f);
+    Vector4 b(4.0f, 3.0f, 2.0f, 1.0f);
+
+    Vector4 sum = a + b;
+    Vector4 scaled = a * 2.0f;
+    float dot = Vector4::Dot(a, b);
+
+    Vector4 projected = Vector4::Project(a, Vector4(1.0f, 0.0f, 0.0f, 0.0f));
+    Vector3 v3 = a.ToVector3();
+
+    return 0;
+}
 ```
 
-## 构造函数
-
-- `Vector4(float x, float y, float z, float w)` - 从四个分量构造
-- `explicit Vector4(const Vector3& v, float w = 0.0f)` - 从 Vector3 构造
-
-## 静态工厂方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| [Zero()](zero.md) | `Vector4` | 返回 (0, 0, 0, 0) |
-| [One()](one.md) | `Vector4` | 返回 (1, 1, 1, 1) |
-
-## 静态数学方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| [Dot(a, b)](dot.md) | `float` | 4D 点积 |
-| [Project(vector, onNormal)](project.md) | `Vector4` | 投影 |
-
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| [ToVector3()](tovector3.md) | `Vector3` | 转换到 Vector3（丢弃 w） |
-
-## 运算符
-
-- 算术: `+`, `-`, `*` (scalar)
-- 下标: `operator[]` (0=x, 1=y, 2=z, 3=w)
-- 比较: `==`, `!=`
-
 ## 相关文档
 
-- [Math 模块总览](../math.md) - 返回 Math 模块总览
+- [Math 模块总览](../math.md) - Math 模块总览

docs/api/math/vector4/zero.md

@@ -1,11 +1,11 @@
 # Vector4::Zero
 
+返回零向量 (0, 0, 0, 0)。
+
 ```cpp
 static Vector4 Zero()
 ```
 
-返回零向量 (0, 0, 0, 0)。
-
 **返回：** `Vector4` - 值为 (0, 0, 0, 0) 的向量
 
 **复杂度：** O(1)
@@ -15,3 +15,8 @@ static Vector4 Zero()
 ```cpp
 Vector4 origin = Vector4::Zero();
 ```
+
+## 相关文档
+
+- [Vector4 总览](vector4.md)
+