docs: update math API docs

docs/api/math/matrix3/inverse.md

@@ -6,13 +6,19 @@ Matrix3 Inverse() const
 
 返回矩阵的逆矩阵。
 
-**返回：** `Matrix3` - 逆矩阵
+**返回：** `Matrix3` - 逆矩阵。如果行列式接近零（< EPSILON），则返回单位矩阵。
+
+**异常：** 当矩阵奇异（行列式为零）时，返回单位矩阵而非抛出异常。
 
 **复杂度：** O(1)
 
 **示例：**
 
 ```cpp
-Matrix3 mat = ...;
+Matrix3 mat = Matrix3::RotationY(0.5f);
 Matrix3 inv = mat.Inverse();
-```
+
+// 验证：M * M⁻¹ ≈ I
+Matrix3 identity = mat * inv;
+// identity 应接近单位矩阵
+```

docs/api/math/matrix3/matrix3.md

@@ -1,20 +1,23 @@
 # Matrix3 / Matrix3x3
 
-3x3 矩阵结构体，用于表示 3D 旋转和缩放变换。
+**命名空间**: `XCEngine::Math`
 
-**头文件：** `#include <XCEngine/Math/Matrix3.h>`
+**类型**: `struct`
 
-**命名空间：** `XCEngine::Math`
+**头文件**: `XCEngine/Math/Matrix3.h`
 
-## 类型别名
+**描述**: 3x3 矩阵，用于旋转变换和线性代数运算。
 
-```cpp
-using Matrix3 = Matrix3x3;
-```
+## 概述
 
-## 存储方式
+Matrix3（别名 Matrix3x3）是一个 3x3 浮点矩阵结构体，主要用于图形引擎中的旋转变换和线性代数运算。
 
-行优先存储 (row-major)：
+**设计目的：**
+- 旋转变换（绕 X/Y/Z 轴）
+- 缩放变换
+- 矩阵运算（乘法、转置、求逆、行列式计算）
+
+**存储方式：** 行优先存储 (row-major)
 ```
 m[row][col]
 m[0][0] m[0][1] m[0][2]
@@ -22,36 +25,61 @@ m[1][0] m[1][1] m[1][2]
 m[2][0] m[2][1] m[2][2]
 ```
 
-## 构造函数
+**类型别名：**
+```cpp
+using Matrix3 = Matrix3x3;
+```
 
-- 默认构造函数初始化为零矩阵
+## 结构体成员
 
-## 静态工厂方法
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `m[3][3]` | `float` | 矩阵元素数组，行优先存储 |
 
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| [Identity()](identity.md) | `Matrix3` | 单位矩阵 |
-| [Zero()](zero.md) | `Matrix3` | 零矩阵 |
-| [RotationX(radians)](rotationx.md) | `Matrix3` | X 轴旋转矩阵 |
-| [RotationY(radians)](rotationy.md) | `Matrix3` | Y 轴旋转矩阵 |
-| [RotationZ(radians)](rotationz.md) | `Matrix3` | Z 轴旋转矩阵 |
-| [Scale(scale)](scale.md) | `Matrix3` | 缩放矩阵 |
+## 公共方法
 
-## 实例方法
+| 方法 | 描述 |
+|------|------|
+| [`Identity()`](identity.md) | 获取单位矩阵 |
+| [`Zero()`](zero.md) | 获取零矩阵 |
+| [`RotationX()`](rotation-x.md) | 创建绕 X 轴旋转矩阵 |
+| [`RotationY()`](rotation-y.md) | 创建绕 Y 轴旋转矩阵 |
+| [`RotationZ()`](rotation-z.md) | 创建绕 Z 轴旋转矩阵 |
+| [`Scale()`](scale.md) | 创建缩放矩阵 |
+| [`operator*(Matrix3)`](operator-mul-matrix3.md) | 矩阵乘法 |
+| [`operator*(Vector3)`](operator-mul-vector3.md) | 矩阵-向量乘法 |
+| [`Transpose()`](transpose.md) | 转置矩阵 |
+| [`Inverse()`](inverse.md) | 逆矩阵 |
+| [`Determinant()`](determinant.md) | 行列式 |
+| [`operator[]`](./operator-subscript.md) | 访问矩阵元素 |
 
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| [Transpose()](transpose.md) | `Matrix3` | 转置矩阵 |
-| [Inverse()](inverse.md) | `Matrix3` | 逆矩阵 |
-| [Determinant()](determinant.md) | `float` | 行列式 |
+## 使用示例
 
-## 运算符
+```cpp
+#include <XCEngine/Math/Matrix3.h>
+#include <XCEngine/Math/Vector3.h>
 
-| 运算符 | 描述 |
-|--------|------|
-| `operator*(Matrix3, Matrix3)` | 矩阵乘法 |
-| `operator*(Matrix3, Vector3)` | 矩阵-向量乘法 |
+using namespace XCEngine::Math;
+
+// 创建绕 Y 轴旋转 45 度的矩阵
+Matrix3 rotation = Matrix3::RotationY(0.785f); // PI/4
+
+// 对向量进行变换
+Vector3 v(1.0f, 0.0f, 0.0f);
+Vector3 rotated = rotation * v;
+
+// 矩阵运算
+Matrix3 m1 = Matrix3::RotationX(0.5f);
+Matrix3 m2 = Matrix3::RotationY(0.3f);
+Matrix3 combined = m1 * m2;
+
+// 求逆矩阵
+Matrix3 inv = combined.Inverse();
+float det = combined.Determinant();
+```
 
 ## 相关文档
 
-- [Math 模块总览](../math.md) - 返回 Math 模块总览
+- [Matrix4](../matrix4/matrix4.md) - 4x4 矩阵
+- [Vector3](../vector3/vector3.md) - 三维向量
+- [Math 模块总览](../math.md) - 返回模块总览

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

@@ -0,0 +1,24 @@
+# Matrix3::operator* (Matrix3)
+
+```cpp
+Matrix3 operator*(const Matrix3& other) const
+```
+
+矩阵乘法运算，将当前矩阵与另一个矩阵相乘。
+
+**参数：**
+- `other` - 另一个矩阵
+
+**返回：** `Matrix3` - 乘积矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 rot = Matrix3::RotationZ(Math::Radians(45.0f));
+Matrix3 scale = Matrix3::Scale(Vector3(2.0f, 2.0f, 1.0f));
+
+// 先缩放后旋转
+Matrix3 transform = rot * scale;
+```

docs/api/math/matrix3/operator-mul-vector3.md

@@ -0,0 +1,24 @@
+# Matrix3::operator* (Vector3)
+
+```cpp
+Vector3 operator*(const Vector3& v) const
+```
+
+矩阵-向量乘法运算，将矩阵应用于向量。
+
+**参数：**
+- `v` - 三维向量
+
+**返回：** `Vector3` - 变换后的向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 rotation = Matrix3::RotationZ(Math::Radians(90.0f));
+Vector3 v(1.0f, 0.0f, 0.0f);
+
+Vector3 rotated = rotation * v;
+// 结果: approximately (0, 1, 0)
+```

docs/api/math/matrix3/operator-subscript.md

@@ -0,0 +1,27 @@
+# Matrix3::operator[]
+
+```cpp
+float* operator[](int row)
+const float* operator[](int row) const
+```
+
+访问矩阵指定行的元素。
+
+**参数：**
+- `row` - 行索引（0-2）
+
+**返回：** `float*` / `const float*` - 指向该行首元素的指针
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 m;
+m[0][0] = 1; m[0][1] = 2; m[0][2] = 3;
+m[1][0] = 4; m[1][1] = 5; m[1][2] = 6;
+m[2][0] = 7; m[2][1] = 8; m[2][2] = 9;
+
+// 访问元素
+float val = m[1][2];  // 6
+```

docs/api/math/matrix3/rotation-x.md

@@ -0,0 +1,24 @@
+# Matrix3::RotationX
+
+```cpp
+static Matrix3 RotationX(float radians)
+```
+
+返回绕 X 轴旋转的 3x3 旋转矩阵。
+
+**参数：**
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Matrix3` - 绕 X 轴旋转的矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 rotX = Matrix3::RotationX(Math::Radians(90.0f));
+// 结果（绕 X 轴旋转 90 度）:
+// [1  0   0]
+// [0  0  -1]
+// [0  1   0]
+```

docs/api/math/matrix3/rotation-y.md

@@ -0,0 +1,24 @@
+# Matrix3::RotationY
+
+```cpp
+static Matrix3 RotationY(float radians)
+```
+
+返回绕 Y 轴旋转的 3x3 旋转矩阵。
+
+**参数：**
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Matrix3` - 绕 Y 轴旋转的矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 rotY = Matrix3::RotationY(Math::Radians(90.0f));
+// 结果（绕 Y 轴旋转 90 度）:
+// [0  0  1]
+// [0  1  0]
+// [-1 0  0]
+```

docs/api/math/matrix3/rotation-z.md

@@ -0,0 +1,24 @@
+# Matrix3::RotationZ
+
+```cpp
+static Matrix3 RotationZ(float radians)
+```
+
+返回绕 Z 轴旋转的 3x3 旋转矩阵。
+
+**参数：**
+- `radians` - 旋转角度（弧度）
+
+**返回：** `Matrix3` - 绕 Z 轴旋转的矩阵
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Matrix3 rotZ = Matrix3::RotationZ(Math::Radians(45.0f));
+// 结果（绕 Z 轴旋转 45 度）:
+// [ 0.707 -0.707  0]
+// [ 0.707  0.707  0]
+// [ 0      0      1]
+```

docs/api/math/matrix3/rotationx.md

@@ -1,20 +0,0 @@
-# Matrix3::RotationX
-
-```cpp
-static Matrix3 RotationX(float radians)
-```
-
-创建绕 X 轴旋转的矩阵。
-
-**参数：**
-- `radians` - 旋转角度（弧度）
-
-**返回：** `Matrix3` - 旋转矩阵
-
-**复杂度：** O(1)
-
-**示例：**
-
-```cpp
-Matrix3 rotX = Matrix3::RotationX(Math::HALF_PI);
-```

docs/api/math/matrix3/rotationy.md

@@ -1,20 +0,0 @@
-# Matrix3::RotationY
-
-```cpp
-static Matrix3 RotationY(float radians)
-```
-
-创建绕 Y 轴旋转的矩阵。
-
-**参数：**
-- `radians` - 旋转角度（弧度）
-
-**返回：** `Matrix3` - 旋转矩阵
-
-**复杂度：** O(1)
-
-**示例：**
-
-```cpp
-Matrix3 rotY = Matrix3::RotationY(Math::HALF_PI);
-```

docs/api/math/matrix3/rotationz.md

@@ -1,20 +0,0 @@
-# Matrix3::RotationZ
-
-```cpp
-static Matrix3 RotationZ(float radians)
-```
-
-创建绕 Z 轴旋转的矩阵。
-
-**参数：**
-- `radians` - 旋转角度（弧度）
-
-**返回：** `Matrix3` - 旋转矩阵
-
-**复杂度：** O(1)
-
-**示例：**
-
-```cpp
-Matrix3 rotZ = Matrix3::RotationZ(Math::HALF_PI);
-```