docs: 重构 API 文档结构并修正源码准确性

- 重组文档目录结构: 每个模块的概述页移动到模块子目录 - 重命名 index.md 为 main.md - 修正所有模块文档中的错误: - math: FromEuler→FromEulerAngles, TransformDirection 包含缩放, Box 是 OBB, Color::ToRGBA 格式 - containers: 新增 operator==/!= 文档, 补充 std::hash DJB 算法细节 - core: 修复 types 链接错误 - debug: LogLevelToString 返回大写, timestamp 是秒, Profiler 空实现标注, Windows API vs ANSI - memory: 修复头文件路径, malloc vs operator new, 新增方法文档 - resources: 修复 Shader/Texture 链接错误 - threading: TaskSystem::Wait 空实现标注, ReadWriteLock 重入描述, LambdaTask 链接 - 验证: fix_links.py 确认 0 个断裂引用
2026-03-19 00:22:30 +08:00
parent d0e16962c8
commit dc850d7739
1012 changed files with 26673 additions and 9222 deletions
--- a/docs/api/containers/array/array.md
+++ b/docs/api/containers/array/array.md
@@ -0,0 +1,94 @@
+# Array
+
+**命名空间**: `XCEngine::Containers`
+
+**类型**: `class` (template)
+
+**描述**: 模板动态数组容器，提供自动扩容的数组实现。
+
+## 概述
+
+`Array<T>` 是一个模板动态数组容器，提供了类似 `std::vector` 的功能，但针对游戏引擎进行了优化。
+
+## 类型别名
+
+| 别名 | 类型 | 描述 |
+|------|------|------|
+| `Iterator` | `T*` | 迭代器类型 |
+| `ConstIterator` | `const T*` | 常量迭代器类型 |
+
+## 公共方法
+
+### 构造/析构
+
+| 方法 | 描述 |
+|------|------|
+| [Constructor](constructor.md) | 构造数组实例 |
+| [Copy/Move Constructor](copy-move-constructor.md) | 拷贝或移动构造 |
+| [Destructor](destructor.md) | 析构函数 |
+| [operator=](operator-assign.md) | 赋值运算符 |
+
+### 元素访问
+
+| 方法 | 描述 |
+|------|------|
+| [operator[]](./operator-subscript.md) | 下标访问 |
+| [Data](data.md) | 获取原始数据指针 |
+| [Front/Back](front-back.md) | 获取首/尾元素引用 |
+
+### 容量管理
+
+| 方法 | 描述 |
+|------|------|
+| [Size/Capacity/Empty](size.md) | 获取尺寸信息 |
+| [Clear](clear.md) | 清空所有元素 |
+| [Reserve](reserve.md) | 预留容量 |
+| [Resize](resize.md) | 调整大小 |
+
+### 元素操作
+
+| 方法 | 描述 |
+|------|------|
+| [PushBack](pushback.md) | 尾部添加（拷贝/移动） |
+| [EmplaceBack](emplaceback.md) | 就地构造尾部添加 |
+| [PopBack](popback.md) | 尾部移除 |
+
+### 迭代器
+
+| 方法 | 描述 |
+|------|------|
+| [begin/end](iterator.md) | 获取迭代器 |
+
+### 内存分配器
+
+| 方法 | 描述 |
+|------|------|
+| [SetAllocator](setallocator.md) | 设置内存分配器 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Containers/Array.h>
+
+// 基本用法
+Containers::Array<int> arr;
+arr.PushBack(1);
+arr.PushBack(2);
+arr.PushBack(3);
+
+// 使用 initializer_list
+Containers::Array<int> arr2 = {1, 2, 3, 4, 5};
+
+// 迭代
+for (auto& elem : arr) {
+    printf("%d\n", elem);
+}
+
+// 使用 EmplaceBack
+arr.EmplaceBack(4);
+```
+
+## 相关文档
+
+- [HashMap](../hashmap/hashmap.md) - 哈希表容器
+- [Memory 模块](../../memory/memory.md) - 内存分配器
--- a/docs/api/containers/array/clear.md
+++ b/docs/api/containers/array/clear.md
@@ -0,0 +1,36 @@
+# Array::Clear()
+
+```cpp
+void Clear();
+```
+
+清空数组中的所有元素。
+
+**行为：**
+- 调用所有元素的析构函数
+- 将 `Size()` 设为 0
+- **不释放底层内存**，`Capacity()` 保持不变
+
+**线程安全：** ❌ 清空期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {1, 2, 3, 4, 5};
+
+arr.Size();      // 5
+arr.Capacity();  // 8（假设自动扩容到 8）
+
+arr.Clear();
+
+arr.Size();      // 0
+arr.Capacity();  // 8（内存未被释放）
+
+// 可继续添加元素，不会重新分配内存
+arr.PushBack(10);
+arr.PushBack(20);
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览
--- a/docs/api/containers/array/constructor.md
+++ b/docs/api/containers/array/constructor.md
@@ -0,0 +1,44 @@
+# Array::Array()
+
+```cpp
+Array() = default;
+explicit Array(size_t capacity);
+Array(size_t count, const T& value);
+Array(std::initializer_list<T> init);
+```
+
+构造一个 `Array<T>` 实例。
+
+**默认构造**：构造空数组，不分配内存。
+
+**容量构造**：预分配指定容量的内存，但不设置元素数量。适用于已知大致元素数量时减少重新分配。
+
+**数量构造**：创建 `count` 个元素，每个元素都是 `value` 的拷贝。使用拷贝构造，不调用默认构造。
+
+**初始化列表构造**：使用 C++ initializer_list 语法创建数组。
+
+**参数：**
+- `capacity` - 预分配的容量大小
+- `count` - 元素数量
+- `value` - 每个元素的初始值
+- `init` - initializer_list 初始化列表
+
+**示例：**
+
+```cpp
+// 默认构造
+Containers::Array<int> arr1;
+
+// 预分配容量（不设置元素）
+Containers::Array<int> arr2(100);
+
+// 创建 10 个元素，初始值为 42
+Containers::Array<int> arr3(10, 42);
+
+// 使用 initializer_list
+Containers::Array<int> arr4 = {1, 2, 3, 4, 5};
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览
--- a/docs/api/containers/array/copy-move-constructor.md
+++ b/docs/api/containers/array/copy-move-constructor.md
@@ -0,0 +1,44 @@
+# Array::Array() - 拷贝/移动构造
+
+```cpp
+Array(const Array& other);
+Array(Array&& other) noexcept;
+```
+
+拷贝或移动构造一个新数组。
+
+**拷贝构造：**
+- 分配与 `other` 相同容量的内存
+- 拷贝 `other` 中所有元素
+
+**移动构造：**
+- 接管 `other` 的所有资源（数据指针、容量、大小）
+- 将 `other` 置为空状态（`m_data = nullptr, m_size = 0, m_capacity = 0`）
+- 不拷贝、不移动任何元素数据，性能 O(1)
+
+**参数：**
+- `other` - 源数组
+
+**异常：**
+- 拷贝构造：元素拷贝可能抛出异常
+- 移动构造：`noexcept`，不抛出异常
+
+**线程安全：** ❌ 构造期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr1 = {1, 2, 3};
+
+// 拷贝构造
+Containers::Array<int> arr2(arr1);    // arr2 = {1, 2, 3}
+
+// 移动构造
+Containers::Array<int> arr3(std::move(arr1));
+// arr3 = {1, 2, 3}
+// arr1 现在为空，Size() == 0
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览
--- a/docs/api/containers/array/data.md
+++ b/docs/api/containers/array/data.md
@@ -0,0 +1,30 @@
+# Array::Data()
+
+```cpp
+T* Data();
+const T* Data() const;
+```
+
+获取指向底层数组数据的原始指针。
+
+**用途：** 用于与 C 风格 API 或需要直接访问内存的场景（如与 GPU 通信）。
+
+**返回：** 指向底层连续内存块的指针。如果数组为空，返回 `nullptr`。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Containers::Array<float> arr = {1.0f, 2.0f, 3.0f};
+
+float* raw = arr.Data();
+size_t count = arr.Size();
+
+// 可用于与 C API 交互
+// memcpy(dst, arr.Data(), arr.Size() * sizeof(float));
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览
--- a/docs/api/containers/array/destructor.md
+++ b/docs/api/containers/array/destructor.md
@@ -0,0 +1,28 @@
+# Array::~Array()
+
+```cpp
+~Array();
+```
+
+销毁数组，释放所有已分配的元素并释放内存。
+
+**行为：**
+- 调用所有元素的析构函数
+- 释放底层数据缓冲区内存
+
+**注意：** 使用 RAII 模式，无需手动调用析构。
+
+**线程安全：** ❌ 析构期间不可并发访问
+
+**示例：**
+
+```cpp
+{
+    Containers::Array<int> arr = {1, 2, 3};
+    // 使用 arr...
+} // arr 在此自动销毁，析构函数被调用
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览
--- a/docs/api/containers/array/emplaceback.md
+++ b/docs/api/containers/array/emplaceback.md
@@ -0,0 +1,47 @@
+# Array::EmplaceBack()
+
+```cpp
+template<typename... Args>
+T& EmplaceBack(Args&&... args);
+```
+
+在数组末尾就地构造一个元素，直接在内存中构造，不产生临时对象。
+
+**优势：**
+- 避免拷贝或移动开销
+- 直接在底层缓冲区末尾构造元素
+- 参数完美转发，支持任意构造参数
+
+**参数：**
+- `args` - 转发给 `T` 构造函数的参数包
+
+**返回：** 新构造元素的引用
+
+**复杂度：** 均摊 O(1)
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+struct Vertex {
+    float x, y, z;
+    Vertex(float x_, float y_, float z_) : x(x_), y(y_), z(z_) {}
+};
+
+Containers::Array<Vertex> vertices;
+
+// EmplaceBack 直接构造，不产生临时 Vertex 对象
+vertices.EmplaceBack(1.0f, 2.0f, 3.0f);
+vertices.EmplaceBack(4.0f, 5.0f, 6.0f);
+
+// 对比 PushBack（需要先构造临时对象）
+Vertex v(7.0f, 8.0f, 9.0f);
+vertices.PushBack(v);  // 产生拷贝或移动
+
+// EmplaceBack 更高效，始终优先使用
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览
--- a/docs/api/containers/array/front-back.md
+++ b/docs/api/containers/array/front-back.md
@@ -0,0 +1,38 @@
+# Array::Front() / Back()
+
+```cpp
+T& Front();
+const T& Front() const;
+T& Back();
+const T& Back() const;
+```
+
+获取数组首尾元素的引用。
+
+**Front()：** 返回第一个元素（`index == 0`）的引用。
+
+**Back()：** 返回最后一个元素（`index == Size() - 1`）的引用。
+
+**前置条件：** 数组必须非空，否则行为未定义。
+
+**返回：** 首/尾元素的引用
+
+**复杂度：** O(1)
+
+**线程安全：** ❌ 访问期间不可并发修改
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {10, 20, 30};
+
+int& first = arr.Front();   // first == 10
+int& last = arr.Back();     // last == 30
+
+arr.Front() = 5;            // arr 现在是 {5, 20, 30}
+arr.Back() = 100;           // arr 现在是 {5, 20, 100}
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览
--- a/docs/api/containers/array/iterator.md
+++ b/docs/api/containers/array/iterator.md
@@ -0,0 +1,45 @@
+# Array::begin() / end()
+
+```cpp
+Iterator begin();
+Iterator end();
+ConstIterator begin() const;
+ConstIterator end() const;
+```
+
+获取数组的迭代器，用于范围遍历。
+
+**begin()：** 返回指向第一个元素的迭代器。如果数组为空，返回值等于 `end()`。
+
+**end()：** 返回指向"最后一个元素之后"位置的迭代器（哨兵）。这是一个越界位置，不可解引用。
+
+**迭代器类型：** `Iterator = T*`（原始指针），因此支持指针算术运算。
+
+**复杂度：** O(1)
+
+**线程安全：** ❌ 迭代期间不可并发修改数组
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {10, 20, 30, 40, 50};
+
+// 范围 for 循环（推荐）
+for (int val : arr) {
+    printf("%d\n", val);
+}
+
+// 手动迭代器
+for (auto it = arr.begin(); it != arr.end(); ++it) {
+    printf("%d\n", *it);
+}
+
+// 指针算术（因为迭代器就是指针）
+int* ptr = arr.begin();
+ptr += 2;  // 指向第三个元素
+*ptr;       // 30
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览
--- a/docs/api/containers/array/operator-assign.md
+++ b/docs/api/containers/array/operator-assign.md
@@ -0,0 +1,44 @@
+# Array::operator=
+
+```cpp
+Array& operator=(const Array& other);
+Array& operator=(Array&& other) noexcept;
+```
+
+赋值运算符，用另一个数组的内容替换当前数组的内容。
+
+**拷贝赋值（`=`）：**
+- 先销毁当前所有元素
+- 分配与 `other` 相同大小的内存
+- 拷贝 `other` 中所有元素
+
+**移动赋值（`=`）：**
+- 先销毁当前所有元素
+- 接管 `other` 的所有资源（数据指针、容量）
+- 将 `other` 置为空状态
+
+**参数：**
+- `other` - 源数组
+
+**返回：** 引用自身（`*this`）
+
+**异常：**
+- 拷贝赋值：`other` 元素拷贝可能抛出异常
+
+**线程安全：** ❌ 赋值期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr1 = {1, 2, 3};
+Containers::Array<int> arr2;
+
+arr2 = arr1;      // 拷贝赋值，arr2 现在是 {1, 2, 3}
+
+Containers::Array<int> arr3 = {4, 5};
+arr2 = std::move(arr3); // 移动赋值，arr2 现在是 {4, 5}，arr3 为空
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览
--- a/docs/api/containers/array/operator-subscript.md
+++ b/docs/api/containers/array/operator-subscript.md
@@ -0,0 +1,39 @@
+# Array::operator[]
+
+```cpp
+T& operator[](size_t index);
+const T& operator[](size_t index) const;
+```
+
+按下标访问数组元素，不进行边界检查。
+
+**行为：**
+- 返回指定索引处元素的引用
+- 不进行下标越界检查，性能最优
+- 可用于读取和修改元素（非常量版本）
+
+**参数：**
+- `index` - 元素下标，从 0 开始
+
+**返回：** 元素的引用（常量版本返回常量引用）
+
+**复杂度：** O(1)
+
+**线程安全：** ❌ 访问元素期间不可并发修改
+
+**注意：** 不会进行边界检查。如果 `index >= Size()`，行为未定义。如需边界检查，请使用 `At()` 方法（如果存在）或自行检查。
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {10, 20, 30};
+
+int first = arr[0];     // first == 10
+int last = arr[2];       // last == 30
+
+arr[1] = 25;            // arr 现在是 {10, 25, 30}
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览
--- a/docs/api/containers/array/popback.md
+++ b/docs/api/containers/array/popback.md
@@ -0,0 +1,38 @@
+# Array::PopBack()
+
+```cpp
+void PopBack();
+```
+
+移除数组末尾的元素，并调用其析构函数。
+
+**前置条件：** 数组必须非空（`Size() > 0`）。如果数组为空，行为未定义。
+
+**行为：**
+- 将 `Size()` 减 1
+- 调用被移除元素的析构函数
+- **不释放底层内存**
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {10, 20, 30, 40, 50};
+
+arr.Size();  // 5
+
+arr.PopBack();  // 移除 50
+
+arr.Size();  // 4
+// arr = {10, 20, 30, 40}
+
+arr.PopBack();
+arr.PopBack();
+// arr = {10, 20}
+// Capacity() 仍为之前的值（如 8）
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览
--- a/docs/api/containers/array/pushback.md
+++ b/docs/api/containers/array/pushback.md
@@ -0,0 +1,43 @@
+# Array::PushBack()
+
+```cpp
+void PushBack(const T& value);
+void PushBack(T&& value);
+```
+
+在数组末尾添加一个元素。
+
+**拷贝版本（`const T&`）：**
+- 如果容量不足（`Size() >= Capacity()`），先扩容（容量翻倍）
+- 在末尾位置拷贝构造 `value`
+
+**移动版本（`T&&`）：**
+- 行为同拷贝版本，但使用移动构造
+- 适用于临时对象或右值，避免拷贝开销
+
+**参数：**
+- `value` - 要添加的元素（拷贝或移动）
+
+**复杂度：** 均摊 O(1)。每次添加的摊销成本为常数，因为扩容是翻倍策略。
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<std::string> arr;
+
+// 拷贝添加
+std::string s = "hello";
+arr.PushBack(s);           // s 被拷贝
+
+// 移动添加（更高效）
+arr.PushBack(std::string("world"));  // 直接移动构造
+
+// 临时对象会被隐式移动
+arr.PushBack("temporary"); // 字符串字面量构造后移动
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览
--- a/docs/api/containers/array/reserve.md
+++ b/docs/api/containers/array/reserve.md
@@ -0,0 +1,39 @@
+# Array::Reserve()
+
+```cpp
+void Reserve(size_t capacity);
+```
+
+预分配底层内存容量，确保能容纳至少 `capacity` 个元素而不重新分配。
+
+**行为：**
+- 如果 `capacity > Capacity()`，分配新的内存（容量翻倍策略）
+- 如果 `capacity <= Capacity()`，什么都不做
+- 不改变 `Size()`
+
+**参数：**
+- `capacity` - 目标容量
+
+**用途：** 当已知大致元素数量时，提前分配可以避免多次重新分配带来的性能开销和迭代器失效。
+
+**复杂度：** O(n)，其中 n 为当前元素数量（需要拷贝现有元素到新内存）
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr;
+
+// 预分配 1000 个元素的容量
+arr.Reserve(1000);
+
+// 之后添加 500 个元素不会触发重新分配
+for (int i = 0; i < 500; ++i) {
+    arr.PushBack(i);
+}
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览
--- a/docs/api/containers/array/resize.md
+++ b/docs/api/containers/array/resize.md
@@ -0,0 +1,46 @@
+# Array::Resize()
+
+```cpp
+void Resize(size_t newSize);
+void Resize(size_t newSize, const T& value);
+```
+
+调整数组大小。
+
+**Resize(newSize)：**
+- 如果 `newSize > Size()`：在末尾构造 `newSize - Size()` 个默认构造的元素
+- 如果 `newSize < Size()`：销毁末尾多出的元素
+- 如果 `newSize == Size()`：什么都不做
+
+**Resize(newSize, value)：**
+- 行为同上述，但扩展时使用 `value` 拷贝构造新元素，而非默认构造
+
+**参数：**
+- `newSize` - 新的元素数量
+- `value` - 扩展时用作填充值的元素
+
+**复杂度：** O(n)，涉及元素构造/析构和可能的内存重新分配
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr = {1, 2, 3};
+
+// 扩展到 5 个元素，新元素默认构造为 0
+arr.Resize(5);
+// arr = {1, 2, 3, 0, 0}
+
+// 缩减到 2 个元素
+arr.Resize(2);
+// arr = {1, 2}
+
+// 扩展到 4 个，填充为 -1
+arr.Resize(4, -1);
+// arr = {1, 2, -1, -1}
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览
--- a/docs/api/containers/array/setallocator.md
+++ b/docs/api/containers/array/setallocator.md
@@ -0,0 +1,38 @@
+# Array::SetAllocator()
+
+```cpp
+void SetAllocator(Memory::IAllocator* allocator);
+```
+
+设置数组使用的内存分配器。
+
+**用途：** 允许自定义内存分配策略，如使用对象池、固定大小分配器或调试分配器。
+
+**参数：**
+- `allocator` - 指向 `Memory::IAllocator` 接口的指针。如果为 `nullptr`，使用默认 `::operator new/delete`。
+
+**注意：**
+- 如果数组已有元素，设置新的分配器后，**不会**迁移现有元素
+- 仅影响后续的内存分配操作
+- 通常在构造后立即调用，或在数组为空时调用
+
+**线程安全：** ❌ 操作期间不可并发访问
+
+**示例：**
+
+```cpp
+// 使用线性分配器（适合帧分配）
+auto* linear = new Memory::LinearAllocator(1024 * 1024);
+
+Containers::Array<int> arr;
+arr.SetAllocator(linear);
+
+// 使用内存池分配器
+auto* pool = new Memory::PoolAllocator(sizeof(MyObject), 100);
+Containers::Array<MyObject> objects;
+objects.SetAllocator(pool);
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览
--- a/docs/api/containers/array/size.md
+++ b/docs/api/containers/array/size.md
@@ -0,0 +1,47 @@
+# Array::Size() / Capacity() / Empty()
+
+```cpp
+size_t Size() const;
+size_t Capacity() const;
+bool Empty() const;
+```
+
+获取数组的尺寸信息。
+
+**Size()：** 返回数组中的实际元素数量。
+
+**Capacity()：** 返回底层内存缓冲区能容纳的元素数量，不一定等于 `Size()`。
+
+**Empty()：** 返回数组是否为空（`Size() == 0`）。等价于 `Size() == 0`，但更语义化。
+
+**返回：**
+- `Size()` - 元素数量
+- `Capacity()` - 底层缓冲区容量
+- `Empty()` - 是否为空
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Containers::Array<int> arr;
+
+arr.Size();      // 0
+arr.Capacity();  // 0
+arr.Empty();     // true
+
+arr.PushBack(1);
+arr.PushBack(2);
+
+arr.Size();      // 2
+arr.Capacity();  // 4（自动扩容）
+arr.Empty();     // false
+
+arr.Reserve(100);
+arr.Size();      // 2（元素数量不变）
+arr.Capacity();  // 100（容量增加）
+```
+
+## 相关文档
+
+- [Array 总览](array.md) - 返回类总览