docs: update math API docs

docs/api/math/sphere/contains.md

@@ -4,17 +4,37 @@
 bool Contains(const Vector3& point) const
 ```
 
-检测点是否在球体内（包括表面）。
+检测点是否在球体内（包括球体表面）。使用平方距离比较避免开平方运算。
 
 **参数：**
 - `point` - 要检测的点
 
-**返回：** `bool` - true 表示点在球体内
+**返回：** `bool` - true 表示点在球体内（包括表面）
+
+**线程安全：** ✅
 
 **复杂度：** O(1)
 
 **示例：**
 
 ```cpp
-if (sphere.Contains(point)) { /* point inside */ }
+#include <XCEngine/Math/Sphere.h>
+#include <XCEngine/Math/Vector3.h>
+
+using namespace XCEngine::Math;
+
+Sphere sphere(Vector3(0.0f, 0.0f, 0.0f), 1.0f);
+
+Vector3 inside(0.5f, 0.0f, 0.0f);
+if (sphere.Contains(inside)) {
+}
+
+Vector3 outside(2.0f, 0.0f, 0.0f);
+if (!sphere.Contains(outside)) {
+}
 ```
+
+## 相关文档
+
+- [Sphere](sphere.md) - 返回类总览
+- [Intersects](intersects.md) - 球体相交检测

docs/api/math/sphere/intersects.md

@@ -4,17 +4,33 @@
 bool Intersects(const Sphere& other) const
 ```
 
-检测两个球体是否相交。
+检测两个球体是否相交。相切（外切或内切）也视为相交。使用平方距离比较避免开平方运算。
 
 **参数：**
 - `other` - 另一个球体
 
-**返回：** `bool` - true 表示相交
+**返回：** `bool` - true 表示相交（包括相切）
+
+**线程安全：** ✅
 
 **复杂度：** O(1)
 
 **示例：**
 
 ```cpp
-if (sphere.Intersects(other)) { /* collision */ }
+#include <XCEngine/Math/Sphere.h>
+#include <XCEngine/Math/Vector3.h>
+
+using namespace XCEngine::Math;
+
+Sphere sphere1(Vector3(0.0f, 0.0f, 0.0f), 1.0f);
+Sphere sphere2(Vector3(1.5f, 0.0f, 0.0f), 1.0f);
+
+if (sphere1.Intersects(sphere2)) {
+}
 ```
+
+## 相关文档
+
+- [Sphere](sphere.md) - 返回类总览
+- [Contains](contains.md) - 点包含检测

docs/api/math/sphere/sphere.md

@@ -1,32 +1,54 @@
 # Sphere
 
-3D 球体结构体。
+**命名空间**: `XCEngine::Math`
 
-**头文件：** `#include <XCEngine/Math/Sphere.h>`
+**类型**: `struct`
 
-**命名空间：** `XCEngine::Math`
+**头文件**: `XCEngine/Math/Sphere.h`
 
-## 结构体定义
+**描述**: 球体，用于碰撞检测和范围查询
+
+## 概述
+
+`Sphere` 是三维空间中的球体结构体，包含一个中心点 `center` 和半径 `radius`。主要用于碰撞检测和范围查询等几何计算场景。
+
+## 结构体成员
+
+| 成员 | 类型 | 描述 | 默认值 |
+|------|------|------|--------|
+| `center` | `Vector3` | 球体中心点 | `Vector3::Zero()` |
+| `radius` | `float` | 球体半径 | `0.0f` |
+
+## 公共方法
+
+| 方法 | 描述 | 线程安全 | 复杂度 |
+|------|------|----------|--------|
+| [`Sphere()`](sphere_default_constructor.md) | 默认构造，零初始化 | ✅ | O(1) |
+| [`Sphere(const Vector3&, float)`](sphere_constructor.md) | 从中心和半径构造球体 | ✅ | O(1) |
+| [`Contains`](contains.md) | 检测点是否在球体内 | ✅ | O(1) |
+| [`Intersects`](intersects.md) | 检测两个球体是否相交 | ✅ | O(1) |
+
+## 使用示例
 
 ```cpp
-struct Sphere {
-    Vector3 center = Vector3::Zero();
-    float radius = 0.0f;
-};
+#include <XCEngine/Math/Sphere.h>
+#include <XCEngine/Math/Vector3.h>
+
+using namespace XCEngine::Math;
+
+Sphere sphere(Vector3(0.0f, 0.0f, 0.0f), 1.0f);
+
+Vector3 point(0.5f, 0.5f, 0.0f);
+if (sphere.Contains(point)) {
+    // point is inside the sphere
+}
+
+Sphere other(Vector3(1.5f, 0.0f, 0.0f), 1.0f);
+if (sphere.Intersects(other)) {
+    // spheres intersect
+}
 ```
 
-## 构造函数
-
-- `Sphere()` - 默认构造
-- `Sphere(const Vector3& center, float radius)` - 从中心和半径构造
-
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| [Contains(point)](contains.md) | `bool` | 点是否在球体内 |
-| [Intersects(other)](intersects.md) | `bool` | 与另一个球体相交 |
-
 ## 相关文档
 
-- [Math 模块总览](../math.md) - 返回 Math 模块总览
+- [Math 模块总览](../math.md) - Math 模块总览

docs/api/math/sphere/sphere_constructor.md

@@ -0,0 +1,32 @@
+# Sphere::Sphere
+
+```cpp
+Sphere(const Vector3& center, float radius)
+```
+
+构造一个指定中心和半径的球体。
+
+**参数：**
+- `center` - 球体中心点
+- `radius` - 球体半径
+
+**返回：** 无
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Sphere.h>
+#include <XCEngine/Math/Vector3.h>
+
+using namespace XCEngine::Math;
+
+Sphere sphere(Vector3(1.0f, 2.0f, 3.0f), 5.0f);
+```
+
+## 相关文档
+
+- [Sphere](sphere.md) - 返回类总览

docs/api/math/sphere/sphere_default_constructor.md

@@ -0,0 +1,28 @@
+# Sphere::Sphere
+
+```cpp
+Sphere()
+```
+
+默认构造函数，使用零初始化 center 为原点，radius 为 0。
+
+**返回：** 无
+
+**线程安全：** ✅
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Math/Sphere.h>
+#include <XCEngine/Math/Vector3.h>
+
+using namespace XCEngine::Math;
+
+Sphere sphere;
+```
+
+## 相关文档
+
+- [Sphere](sphere.md) - 返回类总览