docs: update math API docs

docs/api/math/vector2/cross.md

@@ -4,7 +4,7 @@
 static float Cross(const Vector2& a, const Vector2& b)
 ```
 
-计算两个 2D 向量的叉积（返回标量）。结果为正值表示 b 在 a 的逆时针方向。
+计算两个 2D 向量的叉积（返回标量）。结果为正值表示 b 在 a 的逆时针方向，负值表示 b 在 a 的顺时针方向。
 
 **参数：**
 - `a` - 第一个向量
@@ -12,6 +12,10 @@ static float Cross(const Vector2& a, const Vector2& b)
 
 **返回：** `float` - 叉积结果 a.x * b.y - a.y * b.x
 
+**线程安全：** ✅
+
+**异常：** （无）
+
 **复杂度：** O(1)
 
 **示例：**
@@ -21,3 +25,8 @@ Vector2 a(1.0f, 0.0f);
 Vector2 b(0.0f, 1.0f);
 float cross = Vector2::Cross(a, b);  // 1.0f (逆时针)
 ```
+
+## 相关文档
+
+- [Vector2](vector2.md) - 返回类总览
+- [Dot](Dot.md) - 点积运算

docs/api/math/vector2/dot.md

@@ -4,7 +4,7 @@
 static float Dot(const Vector2& a, const Vector2& b)
 ```
 
-计算两个 2D 向量的点积。
+计算两个 2D 向量的点积。点积结果可用于判断两个向量的方向关系：正值表示夹角小于 90°，零表示垂直，负值表示夹角大于 90°。
 
 **参数：**
 - `a` - 第一个向量
@@ -12,6 +12,10 @@ static float Dot(const Vector2& a, const Vector2& b)
 
 **返回：** `float` - 点积结果 a.x * b.x + a.y * b.y
 
+**线程安全：** ✅
+
+**异常：** （无）
+
 **复杂度：** O(1)
 
 **示例：**
@@ -21,3 +25,8 @@ Vector2 a(1.0f, 0.0f);
 Vector2 b(0.0f, 1.0f);
 float dot = Vector2::Dot(a, b);  // 0.0f
 ```
+
+## 相关文档
+
+- [Vector2](vector2.md) - 返回类总览
+- [Cross](Cross.md) - 叉积运算

docs/api/math/vector2/down.md

@@ -8,6 +8,10 @@ static Vector2 Down()
 
 **返回：** `Vector2` - 值为 (0, -1) 的向量
 
+**线程安全：** ✅
+
+**异常：** （无）
+
 **复杂度：** O(1)
 
 **示例：**
@@ -15,3 +19,7 @@ static Vector2 Down()
 ```cpp
 Vector2 down = Vector2::Down();
 ```
+
+## 相关文档
+
+- [Vector2](vector2.md) - 返回类总览

docs/api/math/vector2/left.md

@@ -8,6 +8,10 @@ static Vector2 Left()
 
 **返回：** `Vector2` - 值为 (-1, 0) 的向量
 
+**线程安全：** ✅
+
+**异常：** （无）
+
 **复杂度：** O(1)
 
 **示例：**
@@ -15,3 +19,7 @@ static Vector2 Left()
 ```cpp
 Vector2 left = Vector2::Left();
 ```
+
+## 相关文档
+
+- [Vector2](vector2.md) - 返回类总览

docs/api/math/vector2/lerp.md

@@ -4,7 +4,7 @@
 static Vector2 Lerp(const Vector2& a, const Vector2& b, float t)
 ```
 
-在线性插值两个向量之间。参数 t 会在 [0, 1] 范围内被限制。
+在两个向量之间进行线性插值。参数 t 会在 [0, 1] 范围内被限制，确保插值结果在两端向量之间。
 
 **参数：**
 - `a` - 起始向量
@@ -13,6 +13,10 @@ static Vector2 Lerp(const Vector2& a, const Vector2& b, float t)
 
 **返回：** `Vector2` - 插值结果
 
+**线程安全：** ✅
+
+**异常：** （无）
+
 **复杂度：** O(1)
 
 **示例：**
@@ -22,3 +26,8 @@ Vector2 start(0.0f, 0.0f);
 Vector2 end(10.0f, 10.0f);
 Vector2 mid = Vector2::Lerp(start, end, 0.5f);  // (5.0f, 5.0f)
 ```
+
+## 相关文档
+
+- [Vector2](vector2.md) - 返回类总览
+- [MoveTowards](movetowards.md) - 朝目标移动

docs/api/math/vector2/magnitude.md

@@ -14,6 +14,10 @@ float Magnitude() const
 
 **返回：** `float` - 向量长度 sqrt(x * x + y * y)
 
+**线程安全：** ✅
+
+**异常：** （无）
+
 **复杂度：** O(1)
 
 **示例：**
@@ -23,3 +27,9 @@ Vector2 v(3.0f, 4.0f);
 float len = v.Magnitude();                    // 5.0f
 float len2 = Vector2::Magnitude(v);          // 5.0f
 ```
+
+## 相关文档
+
+- [Vector2](vector2.md) - 返回类总览
+- [SqrMagnitude](sqrmagnitude.md) - 长度平方（更快）
+- [Normalize](normalize.md) - 归一化向量

docs/api/math/vector2/movetowards.md

@@ -4,7 +4,7 @@
 static Vector2 MoveTowards(const Vector2& current, const Vector2& target, float maxDistance)
 ```
 
-将当前向量朝目标向量移动指定距离。如果距离已小于 maxDistance，则直接返回目标。
+将当前向量朝目标向量移动指定距离。如果当前向量与目标向量的距离已小于 maxDistance，则直接返回目标向量。
 
 **参数：**
 - `current` - 当前向量
@@ -13,6 +13,10 @@ static Vector2 MoveTowards(const Vector2& current, const Vector2& target, float
 
 **返回：** `Vector2` - 移动后的位置
 
+**线程安全：** ✅
+
+**异常：** （无）
+
 **复杂度：** O(1)
 
 **示例：**
@@ -22,3 +26,8 @@ Vector2 current(0.0f, 0.0f);
 Vector2 target(10.0f, 0.0f);
 Vector2 moved = Vector2::MoveTowards(current, target, 3.0f);  // (3.0f, 0.0f)
 ```
+
+## 相关文档
+
+- [Vector2](vector2.md) - 返回类总览
+- [Lerp](lerp.md) - 线性插值

docs/api/math/vector2/normalize.md

@@ -4,13 +4,17 @@
 static Vector2 Normalize(const Vector2& v)
 ```
 
-将向量归一化为单位长度。如果向量长度接近零，返回零向量。
+将向量归一化为单位长度。如果向量长度接近零（小于 EPSILON），返回零向量以避免除零错误。
 
 **参数：**
 - `v` - 要归一化的向量
 
 **返回：** `Vector2` - 归一化后的单位向量
 
+**线程安全：** ✅
+
+**异常：** （无）
+
 **复杂度：** O(1)
 
 **示例：**
@@ -18,3 +22,9 @@ static Vector2 Normalize(const Vector2& v)
 ```cpp
 Vector2 dir = Vector2::Normalize(Vector2(3.0f, 4.0f));  // (0.6f, 0.8f)
 ```
+
+## 相关文档
+
+- [Vector2](vector2.md) - 返回类总览
+- [Magnitude](Magnitude.md) - 计算向量长度
+- [Normalized](normalized.md) - 实例方法归一化

docs/api/math/vector2/normalized.md

@@ -4,10 +4,14 @@
 Vector2 Normalized() const
 ```
 
-返回当前向量的归一化副本（单位长度）。不修改原向量。
+返回当前向量的归一化副本（单位长度）。不修改原向量。如果向量长度接近零（小于 EPSILON），返回零向量。
 
 **返回：** `Vector2` - 归一化后的向量副本
 
+**线程安全：** ✅
+
+**异常：** （无）
+
 **复杂度：** O(1)
 
 **示例：**
@@ -16,3 +20,9 @@ Vector2 Normalized() const
 Vector2 v(3.0f, 4.0f);
 Vector2 unit = v.Normalized();  // (0.6f, 0.8f), v 保持不变
 ```
+
+## 相关文档
+
+- [Vector2](vector2.md) - 返回类总览
+- [Normalize](normalize.md) - 静态方法归一化
+- [Magnitude](magnitude.md) - 计算向量长度

docs/api/math/vector2/one.md

@@ -8,6 +8,10 @@ static Vector2 One()
 
 **返回：** `Vector2` - 值为 (1, 1) 的向量
 
+**线程安全：** ✅
+
+**异常：** （无）
+
 **复杂度：** O(1)
 
 **示例：**
@@ -15,3 +19,7 @@ static Vector2 One()
 ```cpp
 Vector2 unit = Vector2::One();
 ```
+
+## 相关文档
+
+- [Vector2](vector2.md) - 返回类总览

docs/api/math/vector2/right.md

@@ -8,6 +8,10 @@ static Vector2 Right()
 
 **返回：** `Vector2` - 值为 (1, 0) 的向量
 
+**线程安全：** ✅
+
+**异常：** （无）
+
 **复杂度：** O(1)
 
 **示例：**
@@ -15,3 +19,7 @@ static Vector2 Right()
 ```cpp
 Vector2 right = Vector2::Right();
 ```
+
+## 相关文档
+
+- [Vector2](vector2.md) - 返回类总览

docs/api/math/vector2/sqrmagnitude.md

@@ -5,7 +5,7 @@ static float SqrMagnitude(const Vector2& v)
 float SqrMagnitude() const
 ```
 
-计算向量长度的平方。比 Magnitude 更快，避免了开方运算。
+计算向量长度的平方。比 Magnitude 更快，避免了开方运算。在比较相对长度或进行性能敏感的计算时优先使用。
 
 **静态版本参数：**
 - `v` - 要计算长度的向量
@@ -14,6 +14,10 @@ float SqrMagnitude() const
 
 **返回：** `float` - 向量长度平方 x * x + y * y
 
+**线程安全：** ✅
+
+**异常：** （无）
+
 **复杂度：** O(1)
 
 **示例：**
@@ -23,3 +27,8 @@ Vector2 v(3.0f, 4.0f);
 float sqlen = v.SqrMagnitude();                    // 25.0f
 float sqlen2 = Vector2::SqrMagnitude(v);          // 25.0f
 ```
+
+## 相关文档
+
+- [Vector2](vector2.md) - 返回类总览
+- [Magnitude](magnitude.md) - 向量长度

docs/api/math/vector2/up.md

@@ -8,6 +8,10 @@ static Vector2 Up()
 
 **返回：** `Vector2` - 值为 (0, 1) 的向量
 
+**线程安全：** ✅
+
+**异常：** （无）
+
 **复杂度：** O(1)
 
 **示例：**
@@ -15,3 +19,7 @@ static Vector2 Up()
 ```cpp
 Vector2 up = Vector2::Up();
 ```
+
+## 相关文档
+
+- [Vector2](vector2.md) - 返回类总览

docs/api/math/vector2/vector2.md

@@ -1,56 +1,73 @@
 # Vector2
 
-2D 向量结构体，用于表示 2D 空间中的点、方向或颜色。
+**命名空间**: `XCEngine::Math`
 
-**头文件：** `#include <XCEngine/Math/Vector2.h>`
+**类型**: `struct`
 
-**命名空间：** `XCEngine::Math`
+**头文件**: `XCEngine/Math/Vector2.h`
 
-## 结构体定义
+**描述**: 二维向量，支持 2D 游戏开发和图形计算
 
-```cpp
-struct Vector2 {
-    float x = 0.0f;
-    float y = 0.0f;
-};
-```
+## 概述
 
-## 静态工厂方法
+Vector2 是 XCEngine 中的二维向量结构体，用于表示 2D 空间中的点、方向或颜色。提供完整的向量运算支持，包括加、减、乘、除等算术运算，以及点积、叉积、归一化、插值等数学运算。广泛应用于游戏开发中的位置表示、方向控制、碰撞检测和颜色计算等场景。
 
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| [Zero()](zero.md) | `Vector2` | 返回 (0, 0) |
-| [One()](one.md) | `Vector2` | 返回 (1, 1) |
-| [Up()](up.md) | `Vector2` | 返回 (0, 1)，上方向 |
-| [Down()](down.md) | `Vector2` | 返回 (0, -1)，下方向 |
-| [Right()](right.md) | `Vector2` | 返回 (1, 0)，右方向 |
-| [Left()](left.md) | `Vector2` | 返回 (-1, 0)，左方向 |
+## 结构体成员
 
-## 静态数学方法
+| 成员 | 类型 | 描述 | 默认值 |
+|------|------|------|--------|
+| `x` | `float` | X 分量 | `0.0f` |
+| `y` | `float` | Y 分量 | `0.0f` |
 
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| [Dot(a, b)](dot.md) | `float` | 点积 |
-| [Cross(a, b)](cross.md) | `float` | 2D 叉积（返回标量） |
-| [Normalize(v)](normalize.md) | `Vector2` | 归一化向量 |
-| [Magnitude(v)](magnitude.md) | `float` | 向量长度 |
-| [SqrMagnitude(v)](sqrmagnitude.md) | `float` | 长度平方（更快） |
-| [Lerp(a, b, t)](lerp.md) | `Vector2` | 线性插值 |
-| [MoveTowards(current, target, maxDistance)](movetowards.md) | `Vector2` | 朝目标移动 |
+## 公共方法
 
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| [Magnitude()](magnitude.md) | `float` | 获取向量长度 |
-| [SqrMagnitude()](sqrmagnitude.md) | `float` | 获取长度平方 |
-| [Normalized()](normalized.md) | `Vector2` | 获取归一化副本 |
+| 方法 | 描述 |
+|------|------|
+| [`Zero`](Zero.md) | 返回 (0, 0) 零向量 |
+| [`One`](One.md) | 返回 (1, 1) 单位向量 |
+| [`Up`](Up.md) | 返回 (0, 1) 上方向 |
+| [`Down`](Down.md) | 返回 (0, -1) 下方向 |
+| [`Right`](Right.md) | 返回 (1, 0) 右方向 |
+| [`Left`](Left.md) | 返回 (-1, 0) 左方向 |
+| [`Dot`](Dot.md) | 计算两个向量的点积 |
+| [`Cross`](Cross.md) | 计算两个向量的叉积（返回标量） |
+| [`Normalize`](Normalize.md) | 归一化向量为单位长度 |
+| [`Magnitude`](Magnitude.md) | 计算向量长度 |
+| [`SqrMagnitude`](SqrMagnitude.md) | 计算向量长度平方 |
+| [`Lerp`](Lerp.md) | 线性插值 |
+| [`MoveTowards`](MoveTowards.md) | 朝目标移动 |
+| [`Magnitude`](Magnitude.md) | 实例方法，计算当前向量长度 |
+| [`SqrMagnitude`](SqrMagnitude.md) | 实例方法，计算当前向量长度平方 |
+| [`Normalized`](Normalized.md) | 实例方法，返回归一化副本 |
 
 ## 运算符
 
-- 算术: `+`, `-`, `*` (scalar), `/` (scalar)
-- 复合赋值: `+=`, `-=`, `*=`, `/=`
-- 比较: `==`, `!=`
+| 运算符 | 描述 |
+|--------|------|
+| `+`, `-` | 向量加减运算 |
+| `*`, `/` | 向量与标量乘除运算 |
+| `+=`, `-=`, `*=`, `/=` | 复合赋值运算 |
+| `==`, `!=` | 相等性比较（基于 EPSILON 浮点比较） |
+
+## 使用示例
+
+```cpp
+#include "XCEngine/Math/Vector2.h"
+
+using namespace XCEngine::Math;
+
+Vector2 position(5.0f, 3.0f);
+Vector2 velocity(1.0f, 0.5f);
+
+float speed = velocity.Magnitude();
+Vector2 normalizedVel = velocity.Normalized();
+
+Vector2 newPos = position + velocity * speed;
+
+float dotProduct = Vector2::Dot(position, normalizedVel);
+
+Vector2 interpolated = Vector2::Lerp(position, Vector2(10.0f, 10.0f), 0.5f);
+```
 
 ## 相关文档
 

docs/api/math/vector2/zero.md

@@ -8,6 +8,10 @@ static Vector2 Zero()
 
 **返回：** `Vector2` - 值为 (0, 0) 的向量
 
+**线程安全：** ✅
+
+**异常：** （无）
+
 **复杂度：** O(1)
 
 **示例：**
@@ -15,3 +19,7 @@ static Vector2 Zero()
 ```cpp
 Vector2 origin = Vector2::Zero();
 ```
+
+## 相关文档
+
+- [Vector2](vector2.md) - 返回类总览