docs: update math API docs

docs/api/math/color/black.md

@@ -6,6 +6,19 @@ static Color Black()
 
 返回黑色 (0, 0, 0, 1)。
 
-**返回：** `Color`
+**返回：** `Color` - 黑色
 
-**示例：** `Color c = Color::Black();`
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color c = Color::Black();
+```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`White`](white.md) - 返回白色

docs/api/math/color/blue.md

@@ -6,6 +6,19 @@ static Color Blue()
 
 返回蓝色 (0, 0, 1, 1)。
 
-**返回：** `Color`
+**返回：** `Color` - 蓝色
 
-**示例：** `Color c = Color::Blue();`
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color c = Color::Blue();
+```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`Yellow`](yellow.md) - 返回黄色

docs/api/math/color/clear.md

@@ -6,6 +6,19 @@ static Color Clear()
 
 返回透明黑色 (0, 0, 0, 0)。
 
-**返回：** `Color`
+**返回：** `Color` - 透明黑色
 
-**示例：** `Color c = Color::Clear();`
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color c = Color::Clear();
+```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`Black`](black.md) - 返回不透明黑色

docs/api/math/color/color.md

@@ -1,63 +1,93 @@
 # Color
 
-颜色结构体，支持 RGBA 浮点分量。
+**命名空间**: `XCEngine::Math`
 
-**头文件：** `#include <XCEngine/Math/Color.h>`
+**类型**: `struct`
 
-**命名空间：** `XCEngine::Math`
+**头文件**: `XCEngine/Math/Color.h`
 
-## 结构体定义
+**描述**: 颜色结构体，支持 RGBA 浮点分量，用于图形渲染
 
-```cpp
-struct Color {
-    float r = 1.0f;
-    float g = 1.0f;
-    float b = 1.0f;
-    float a = 1.0f;
-};
-```
+## 概述
+
+`Color` 是一个简单的 RGBA 颜色结构体，每个分量使用 32 位浮点数，范围 [0, 1]。默认构造创建白色 (1, 1, 1, 1)。该结构体提供静态工厂方法创建常用颜色，以及颜色插值和格式转换功能。
+
+## 结构体成员
+
+| 成员 | 类型 | 描述 | 默认值 |
+|------|------|------|--------|
+| `r` | `float` | 红色分量，范围 [0, 1] | `1.0f` |
+| `g` | `float` | 绿色分量，范围 [0, 1] | `1.0f` |
+| `b` | `float` | 蓝色分量，范围 [0, 1] | `1.0f` |
+| `a` | `float` | Alpha 分量，范围 [0, 1] | `1.0f` |
 
 ## 构造函数
 
-- `Color()` - 默认构造，初始化为白色 (1, 1, 1, 1)
-- `constexpr Color(float r, float g, float b, float a = 1.0f)` - 从 RGBA 分量构造
+### 默认构造函数
 
-## 静态工厂方法
+```cpp
+Color() = default;
+```
 
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| [White()](white.md) | `Color` | (1, 1, 1, 1) |
-| [Black()](black.md) | `Color` | (0, 0, 0, 1) |
-| [Red()](red.md) | `Color` | (1, 0, 0, 1) |
-| [Green()](green.md) | `Color` | (0, 1, 0, 1) |
-| [Blue()](blue.md) | `Color` | (0, 0, 1, 1) |
-| [Yellow()](yellow.md) | `Color` | (1, 1, 0, 1) |
-| [Cyan()](cyan.md) | `Color` | (0, 1, 1, 1) |
-| [Magenta()](magenta.md) | `Color` | (1, 0, 1, 1) |
-| [Clear()](clear.md) | `Color` | (0, 0, 0, 0)，透明黑 |
+创建白色 (1, 1, 1, 1)。
 
-## 静态方法
+### 带参构造函数
 
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| [Lerp(a, b, t)](lerp.md) | `Color` | 颜色线性插值 |
+```cpp
+constexpr Color(float r, float g, float b, float a = 1.0f)
+```
 
-## 实例方法
+构造指定 RGBA 值的颜色。
 
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| [ToRGBA()](torgba.md) | `uint32_t` | 转换为 32-bit RGBA (0xRRGGBBAA) |
-| [ToVector3()](tovector3.md) | `Vector3` | 转换为 RGB (丢弃 alpha) |
-| [ToVector4()](tovector4.md) | `Vector4` | 转换为 RGBA |
+**参数：**
+- `r` - 红色分量，范围 [0, 1]
+- `g` - 绿色分量，范围 [0, 1]
+- `b` - 蓝色分量，范围 [0, 1]
+- `a` - Alpha 分量，范围 [0, 1]，默认值为 1.0f（完全不透明）
 
-## 运算符
+**返回：** `Color` - 构造的颜色
 
-| 运算符 | 描述 |
-|--------|------|
-| `operator+(Color, Color)` | 颜色相加 |
-| `operator-(Color, Color)` | 颜色相减 |
-| `operator*(Color, float)` | 颜色乘以标量 |
-| `operator/(Color, float)` | 颜色除以标量 |
+**示例：**
+
+```cpp
+Color red(1.0f, 0.0f, 0.0f, 1.0f);
+Color halfAlpha(0.5f, 0.5f, 0.5f);  // a = 1.0f
+```
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [`White`](white.md) | 返回白色 (1, 1, 1, 1) |
+| [`Black`](black.md) | 返回黑色 (0, 0, 0, 1) |
+| [`Red`](red.md) | 返回红色 (1, 0, 0, 1) |
+| [`Green`](green.md) | 返回绿色 (0, 1, 0, 1) |
+| [`Blue`](blue.md) | 返回蓝色 (0, 0, 1, 1) |
+| [`Yellow`](yellow.md) | 返回黄色 (1, 1, 0, 1) |
+| [`Cyan`](cyan.md) | 返回青色 (0, 1, 1, 1) |
+| [`Magenta`](magenta.md) | 返回品红色 (1, 0, 1, 1) |
+| [`Clear`](clear.md) | 返回透明黑色 (0, 0, 0, 0) |
+| [`Lerp`](lerp.md) | 颜色线性插值 |
+| [`ToRGBA`](torgba.md) | 转换为 32-bit RGBA 整数 |
+| [`ToVector3`](tovector3.md) | 转换为 Vector3（丢弃 alpha） |
+| [`ToVector4`](tovector4.md) | 转换为 Vector4 |
+| [`operator+`](operator-add.md) | 颜色相加 |
+| [`operator-`](operator-sub.md) | 颜色相减 |
+| [`operator*`](operator-mul.md) | 颜色乘以标量 |
+| [`operator/`](operator-div.md) | 颜色除以标量 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Math/Color.h>
+
+using namespace XCEngine::Math;
+
+Color c1 = Color::Red();
+Color c2 = Color(0, 1, 0, 1);
+Color blended = Color::Lerp(c1, c2, 0.5f);
+uint32_t rgba = blended.ToRGBA();
+```
 
 ## 相关文档
 

docs/api/math/color/cyan.md

@@ -6,6 +6,19 @@ static Color Cyan()
 
 返回青色 (0, 1, 1, 1)。
 
-**返回：** `Color`
+**返回：** `Color` - 青色
 
-**示例：** `Color c = Color::Cyan();`
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color c = Color::Cyan();
+```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`Magenta`](magenta.md) - 返回品红色

docs/api/math/color/green.md

@@ -6,6 +6,19 @@ static Color Green()
 
 返回绿色 (0, 1, 0, 1)。
 
-**返回：** `Color`
+**返回：** `Color` - 绿色
 
-**示例：** `Color c = Color::Green();`
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color c = Color::Green();
+```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`Red`](red.md) - 返回红色

docs/api/math/color/lerp.md

@@ -9,9 +9,11 @@ static Color Lerp(const Color& a, const Color& b, float t)
 **参数：**
 - `a` - 起始颜色
 - `b` - 结束颜色
-- `t` - 插值因子 (0-1)
+- `t` - 插值因子，范围 [0, 1]。超出范围的值会被 clamp 到 [0, 1]
 
-**返回：** `Color` - 插值结果
+**返回：** `Color` - 插值结果，当 t=0 时返回 a，t=1 时返回 b
+
+**线程安全：** ✅
 
 **复杂度：** O(1)
 
@@ -20,3 +22,7 @@ static Color Lerp(const Color& a, const Color& b, float t)
 ```cpp
 Color lerped = Color::Lerp(Color::Red(), Color::Blue(), 0.5f);
 ```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览

docs/api/math/color/magenta.md

@@ -6,6 +6,19 @@ static Color Magenta()
 
 返回品红色 (1, 0, 1, 1)。
 
-**返回：** `Color`
+**返回：** `Color` - 品红色
 
-**示例：** `Color c = Color::Magenta();`
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color c = Color::Magenta();
+```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`Cyan`](cyan.md) - 返回青色

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

@@ -0,0 +1,29 @@
+# Color::operator+
+
+```cpp
+Color operator+(const Color& other) const
+```
+
+将两个颜色对应分量相加，返回新的颜色。
+
+**参数：**
+- `other` - 要加的另一个颜色
+
+**返回：** `Color` - 分量相加后的新颜色
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color red = Color::Red();
+Color blue = Color::Blue();
+Color purple = red + blue;
+```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`operator-`](operator-sub.md) - 颜色相减

docs/api/math/color/operator-div.md

@@ -0,0 +1,28 @@
+# Color::operator/
+
+```cpp
+Color operator/(float scalar) const
+```
+
+将颜色每个分量除以一个标量值，返回新的颜色。
+
+**参数：**
+- `scalar` - 非零标量除数
+
+**返回：** `Color` - 缩放后的新颜色
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color red = Color::Red();
+Color dimRed = red / 2.0f;
+```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`operator*`](operator-mul.md) - 颜色乘以标量

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

@@ -0,0 +1,28 @@
+# Color::operator*
+
+```cpp
+Color operator*(float scalar) const
+```
+
+将颜色每个分量乘以一个标量值，返回新的颜色。
+
+**参数：**
+- `scalar` - 标量乘数
+
+**返回：** `Color` - 缩放后的新颜色
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color red = Color::Red();
+Color fadedRed = red * 0.5f;
+```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`operator/`](operator-div.md) - 颜色除以标量

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

@@ -0,0 +1,29 @@
+# Color::operator-
+
+```cpp
+Color operator-(const Color& other) const
+```
+
+将两个颜色对应分量相减，返回新的颜色。
+
+**参数：**
+- `other` - 要减去的另一个颜色
+
+**返回：** `Color` - 分量相减后的新颜色
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color red = Color::Red();
+Color purple = Color(1, 0, 1, 1);
+Color blue = purple - red;
+```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`operator+`](operator-add.md) - 颜色相加

docs/api/math/color/red.md

@@ -6,6 +6,19 @@ static Color Red()
 
 返回红色 (1, 0, 0, 1)。
 
-**返回：** `Color`
+**返回：** `Color` - 红色
 
-**示例：** `Color c = Color::Red();`
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color c = Color::Red();
+```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`Green`](green.md) - 返回绿色

docs/api/math/color/torgba.md

@@ -6,7 +6,9 @@ uint32_t ToRGBA() const
 
 将颜色转换为 32-bit RGBA 整数格式。
 
-**返回：** `uint32_t` - RGBA 值 (0xRRGGBBAA)
+**返回：** `uint32_t` - RGBA 值，格式为 `0xRRGGBBAA`（R在最高字节，A在最低字节）
+
+**线程安全：** ✅
 
 **复杂度：** O(1)
 
@@ -16,3 +18,9 @@ uint32_t ToRGBA() const
 Color c(1.0f, 0.0f, 0.0f, 1.0f);
 uint32_t rgba = c.ToRGBA();
 ```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`ToVector3`](tovector3.md) - 转换为 Vector3
+- [`ToVector4`](tovector4.md) - 转换为 Vector4

docs/api/math/color/tovector3.md

@@ -8,6 +8,8 @@ Vector3 ToVector3() const
 
 **返回：** `Vector3` - RGB 值
 
+**线程安全：** ✅
+
 **复杂度：** O(1)
 
 **示例：**
@@ -15,3 +17,9 @@ Vector3 ToVector3() const
 ```cpp
 Vector3 rgb = Color::Red().ToVector3();
 ```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`ToVector4`](tovector4.md) - 转换为 Vector4
+- [`ToRGBA`](torgba.md) - 转换为 RGBA 整数

docs/api/math/color/tovector4.md

@@ -8,6 +8,8 @@ Vector4 ToVector4() const
 
 **返回：** `Vector4` - RGBA 值
 
+**线程安全：** ✅
+
 **复杂度：** O(1)
 
 **示例：**
@@ -15,3 +17,9 @@ Vector4 ToVector4() const
 ```cpp
 Vector4 rgba = Color::Red().ToVector4();
 ```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`ToVector3`](tovector3.md) - 转换为 Vector3（丢弃 alpha）
+- [`ToRGBA`](torgba.md) - 转换为 RGBA 整数

docs/api/math/color/white.md

@@ -6,6 +6,19 @@ static Color White()
 
 返回白色 (1, 1, 1, 1)。
 
-**返回：** `Color`
+**返回：** `Color` - 白色
 
-**示例：** `Color c = Color::White();`
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color c = Color::White();
+```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`Black`](black.md) - 返回黑色

docs/api/math/color/yellow.md

@@ -6,6 +6,19 @@ static Color Yellow()
 
 返回黄色 (1, 1, 0, 1)。
 
-**返回：** `Color`
+**返回：** `Color` - 黄色
 
-**示例：** `Color c = Color::Yellow();`
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Color c = Color::Yellow();
+```
+
+## 相关文档
+
+- [Color](color.md) - 返回类总览
+- [`Blue`](blue.md) - 返回蓝色