docs: update math API docs

docs/api/math/ray/ray.md

@@ -1,44 +1,60 @@
 # Ray
 
-3D 射线结构体，用于光线投射和拾取。
+**命名空间**: `XCEngine::Math`
 
-**头文件：** `#include <XCEngine/Math/Ray.h>`
+**类型**: `struct`
 
-**命名空间：** `XCEngine::Math`
+**头文件**: `XCEngine/Math/Ray.h`
 
-## 结构体定义
+**描述**: 射线，用于 3D 拾取和光线追踪
 
-```cpp
-struct Ray {
-    Vector3 origin;      // 射线起点
-    Vector3 direction;   // 归一化方向
+## 概述
 
-    Ray() = default;
-    Ray(const Vector3& origin, const Vector3& direction);
+`Ray` 表示从原点出发沿特定方向延伸的无限射线。通过 `direction` 方向的归一化，确保射线方向向量为单位长度，支持精确的交点计算。广泛应用于光线追踪、碰撞拾取和视锥体裁剪等图形学场景。
 
-    Vector3 GetPoint(float t) const;
-    bool Intersects(const Sphere& sphere, float& t) const;
-    bool Intersects(const Box& box, float& t) const;
-    bool Intersects(const Plane& plane, float& t) const;
-};
-```
+**注意**：构造时 `direction` 会被自动归一化。
 
-## 构造函数
+## 结构体成员
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `origin` | `Vector3` | 射线起点 |
+| `direction` | `Vector3` | 射线方向（归一化） |
+
+## 公共方法
 
 | 方法 | 描述 |
 |------|------|
-| `Ray()` | 默认构造 |
-| `Ray(origin, direction)` | 从起点和方向构造 |
+| [`Ray()`](ray-constructor-default.md) | 默认构造函数 |
+| [`Ray(origin, direction)`](ray-constructor.md) | 从起点和方向构造（direction 会被自动归一化） |
+| [`GetPoint`](getpoint.md) | 获取射线上 t 距离处的点 |
+| [`Intersects`](intersects-sphere.md) | 与球体相交检测 |
+| [`Intersects`](intersects-box.md) | 与有向包围盒相交检测 |
+| [`Intersects`](intersects-plane.md) | 与平面相交检测 |
 
-## 实例方法
+## 使用示例
 
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| [GetPoint(t)](getpoint.md) | `Vector3` | 获取射线上 t 距离处的点 |
-| [Intersects(sphere, t)](intersects-sphere.md) | `bool` | 与球体相交，输出距离 t |
-| [Intersects(box, t)](intersects-box.md) | `bool` | 与 OBB 相交，输出距离 t |
-| [Intersects(plane, t)](intersects-plane.md) | `bool` | 与平面相交，输出距离 t |
+```cpp
+#include <XCEngine/Math/Ray.h>
+#include <XCEngine/Math/Vector3.h>
+#include <XCEngine/Math/Sphere.h>
+
+using namespace XCEngine::Math;
+
+Ray ray(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 0.0f, 0.0f));
+Vector3 point = ray.GetPoint(5.0f);  // point = (5, 0, 0)
+
+Sphere sphere(Vector3(10.0f, 0.0f, 0.0f), 1.0f);
+float t;
+if (ray.Intersects(sphere, t)) {
+    Vector3 hitPoint = ray.GetPoint(t);
+}
+```
 
 ## 相关文档
 
-- [Math 模块总览](../math.md) - 返回 Math 模块总览
+- [Math 模块总览](../math.md) - Math 模块总览
+- [Vector3](../vector3/vector3.md) - 方向和点类型
+- [Sphere](../sphere/sphere.md) - 球体类型
+- [Box](../box/box.md) - 包围盒类型
+- [Plane](../plane/plane.md) - 平面类型