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/threading/task/addref.md
+++ b/docs/api/threading/task/addref.md
@@ -0,0 +1,27 @@
+# ITask::AddRef
+
+```cpp
+void AddRef()
+```
+
+增加任务的引用计数。用于延长任务的生命周期，使其不会被自动释放。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ITask* task = new MyTask();
+task->AddRef(); // 保持引用，不会在 Release 时被删除
+task->SetPriority(TaskPriority::High);
+TaskSystem::Get().Submit(std::unique_ptr<ITask>(task));
+```
+
+## 相关文档
+
+- [ITask 总览](task.md) - 返回类总览
+- [Release](release.md) - 释放引用计数
--- a/docs/api/threading/task/execute.md
+++ b/docs/api/threading/task/execute.md
@@ -0,0 +1,43 @@
+# ITask::Execute
+
+```cpp
+virtual void Execute() = 0
+```
+
+任务执行逻辑（纯虚方法）。用户必须在派生类中实现此方法以定义任务的具体行为。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** 取决于具体任务实现
+
+**注意：**
+- 此方法由 TaskSystem 的工作线程调用。
+- 任务执行期间如发生未捕获异常，行为未定义。
+
+**示例：**
+
+```cpp
+class ComputeTask : public ITask {
+public:
+    explicit ComputeTask(int n) : m_n(n) {}
+    
+    void Execute() override {
+        int result = 0;
+        for (int i = 0; i < m_n; ++i) {
+            result += i;
+        }
+        printf("Result: %d\n", result);
+    }
+    
+private:
+    int m_n;
+};
+
+TaskSystem::Get().Submit(std::make_unique<ComputeTask>(100));
+```
+
+## 相关文档
+
+- [ITask 总览](task.md) - 返回类总览
--- a/docs/api/threading/task/getid.md
+++ b/docs/api/threading/task/getid.md
@@ -0,0 +1,25 @@
+# ITask::GetId
+
+```cpp
+uint64_t GetId() const
+```
+
+获取任务的唯一标识符。
+
+**参数：** 无
+
+**返回：** `uint64_t` - 任务的唯一 ID
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ITask* task = /* ... */;
+uint64_t id = task->GetId();
+printf("Task ID: %llu\n", (unsigned long long)id);
+```
+
+## 相关文档
+
+- [ITask 总览](task.md) - 返回类总览
--- a/docs/api/threading/task/getpriority.md
+++ b/docs/api/threading/task/getpriority.md
@@ -0,0 +1,27 @@
+# ITask::GetPriority
+
+```cpp
+TaskPriority GetPriority() const
+```
+
+获取任务的优先级。
+
+**参数：** 无
+
+**返回：** `TaskPriority` - 当前任务的优先级
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ITask* task = /* ... */;
+TaskPriority priority = task->GetPriority();
+if (priority == TaskPriority::Critical) {
+    printf("Critical task\n");
+}
+```
+
+## 相关文档
+
+- [ITask 总览](task.md) - 返回类总览
--- a/docs/api/threading/task/getstatus.md
+++ b/docs/api/threading/task/getstatus.md
@@ -0,0 +1,32 @@
+# ITask::GetStatus
+
+```cpp
+TaskStatus GetStatus() const
+```
+
+获取任务的当前状态。
+
+**参数：** 无
+
+**返回：** `TaskStatus` - 当前任务状态
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ITask* task = /* ... */;
+TaskStatus status = task->GetStatus();
+switch (status) {
+    case TaskStatus::Pending:   printf("Pending\n"); break;
+    case TaskStatus::Scheduled: printf("Scheduled\n"); break;
+    case TaskStatus::Running:   printf("Running\n"); break;
+    case TaskStatus::Completed: printf("Completed\n"); break;
+    case TaskStatus::Failed:   printf("Failed\n"); break;
+    case TaskStatus::Canceled:  printf("Canceled\n"); break;
+}
+```
+
+## 相关文档
+
+- [ITask 总览](task.md) - 返回类总览
--- a/docs/api/threading/task/oncancel.md
+++ b/docs/api/threading/task/oncancel.md
@@ -0,0 +1,38 @@
+# ITask::OnCancel
+
+```cpp
+virtual void OnCancel()
+```
+
+任务取消回调。可在派生类中重写此方法，以在任务被取消时执行清理操作。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** 取决于具体实现
+
+**示例：**
+
+```cpp
+class NetworkTask : public ITask {
+public:
+    void Execute() override {
+        for (int i = 0; i < 100; ++i) {
+            if (GetStatus() == TaskStatus::Canceled) {
+                return;
+            }
+            SendPacket(i);
+        }
+    }
+    
+    void OnCancel() override {
+        CloseConnection();
+        printf("Network task canceled\n");
+    }
+};
+```
+
+## 相关文档
+
+- [ITask 总览](task.md) - 返回类总览
--- a/docs/api/threading/task/oncomplete.md
+++ b/docs/api/threading/task/oncomplete.md
@@ -0,0 +1,39 @@
+# ITask::OnComplete
+
+```cpp
+virtual void OnComplete()
+```
+
+任务完成回调。可在派生类中重写此方法，以在任务执行完毕后执行清理或后续操作。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** 取决于具体实现
+
+**示例：**
+
+```cpp
+class DataLoadTask : public ITask {
+public:
+    explicit DataLoadTask(const String& path) : m_path(path) {}
+    
+    void Execute() override {
+        m_data = LoadFromFile(m_path);
+    }
+    
+    void OnComplete() override {
+        printf("Data loaded, size: %zu\n", m_data.Size());
+        ProcessData(m_data);
+    }
+    
+private:
+    String m_path;
+    Containers::Vector<uint8_t> m_data;
+};
+```
+
+## 相关文档
+
+- [ITask 总览](task.md) - 返回类总览
--- a/docs/api/threading/task/release.md
+++ b/docs/api/threading/task/release.md
@@ -0,0 +1,32 @@
+# ITask::Release
+
+```cpp
+void Release()
+```
+
+减少引用计数。当引用计数归零时，对象会自动 delete 自身。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**注意：**
+- 任务提交给 TaskSystem 后，TaskSystem 会自动管理引用计数。
+- 当任务完成且无人持有引用时，任务对象将被自动销毁。
+- 不要在任务执行过程中调用 Release。
+
+**示例：**
+
+```cpp
+ITask* task = new MyTask();
+task->AddRef(); // 引用计数 = 2
+TaskSystem::Get().Submit(std::unique_ptr<ITask>(task)); // 引用计数 = 1
+task->Release(); // 引用计数 = 0，任务被 delete
+```
+
+## 相关文档
+
+- [ITask 总览](task.md) - 返回类总览
+- [AddRef](addref.md) - 增加引用计数
--- a/docs/api/threading/task/setid.md
+++ b/docs/api/threading/task/setid.md
@@ -0,0 +1,28 @@
+# ITask::SetId
+
+```cpp
+void SetId(uint64_t id)
+```
+
+设置任务的唯一标识符。通常由 TaskSystem 在提交时自动分配。
+
+**参数：**
+- `id` - 要设置的唯一标识符
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+class MyTask : public ITask {
+public:
+    MyTask() { SetId(GenerateId()); }
+    void Execute() override { /* ... */ }
+};
+```
+
+## 相关文档
+
+- [ITask 总览](task.md) - 返回类总览
--- a/docs/api/threading/task/setpriority.md
+++ b/docs/api/threading/task/setpriority.md
@@ -0,0 +1,28 @@
+# ITask::SetPriority
+
+```cpp
+void SetPriority(TaskPriority priority)
+```
+
+设置任务的优先级。
+
+**参数：**
+- `priority` - 新的优先级（参见 TaskPriority 枚举）
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**注意：** 任务提交后修改优先级可能不会立即生效，取决于任务系统实现。
+
+**示例：**
+
+```cpp
+auto task = std::make_unique<MyTask>();
+task->SetPriority(TaskPriority::High);
+TaskSystem::Get().Submit(std::move(task));
+```
+
+## 相关文档
+
+- [ITask 总览](task.md) - 返回类总览
--- a/docs/api/threading/task/setstatus.md
+++ b/docs/api/threading/task/setstatus.md
@@ -0,0 +1,35 @@
+# ITask::SetStatus
+
+```cpp
+void SetStatus(TaskStatus status)
+```
+
+设置任务的当前状态。
+
+**参数：**
+- `status` - 新的状态（参见 TaskStatus 枚举）
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**注意：** 正常情况下由 TaskSystem 管理状态。手动设置状态可能干扰任务系统的正常调度。
+
+**示例：**
+
+```cpp
+class ConditionalTask : public ITask {
+public:
+    void Execute() override {
+        if (someCondition) {
+            SetStatus(TaskStatus::Failed);
+            return;
+        }
+        // 正常处理
+    }
+};
+```
+
+## 相关文档
+
+- [ITask 总览](task.md) - 返回类总览
--- a/docs/api/threading/task/task.md
+++ b/docs/api/threading/task/task.md
@@ -0,0 +1,97 @@
+# ITask
+
+**命名空间**: `XCEngine::Threading`
+
+**类型**: `class` (abstract)
+
+**头文件**: `XCEngine/Threading/Task.h`
+
+**描述**: 任务基类抽象接口和任务状态/优先级枚举定义。
+
+## 概述
+
+`ITask` 是任务系统的核心抽象基类。用户需要继承此类并实现 `Execute()` 方法来定义具体的任务逻辑。任务系统通过引用计数自动管理任务生命周期。
+
+## TaskPriority 枚举
+
+任务优先级枚举（数值越小优先级越高）。
+
+| 值 | 描述 |
+|----|------|
+| `Critical` | 关键优先级（0） |
+| `High` | 高优先级（1） |
+| `Normal` | 普通优先级（2） |
+| `Low` | 低优先级（3） |
+| `Idle` | 空闲优先级（4） |
+
+## TaskStatus 枚举
+
+任务状态枚举。
+
+| 值 | 描述 |
+|----|------|
+| `Pending` | 等待中 |
+| `Scheduled` | 已调度 |
+| `Running` | 运行中 |
+| `Completed` | 已完成 |
+| `Failed` | 失败 |
+| `Canceled` | 已取消 |
+
+## ITask 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| [`Execute`](execute.md) | 任务执行逻辑（纯虚） |
+| [`OnComplete`](oncomplete.md) | 任务完成回调（可重写） |
+| [`OnCancel`](oncancel.md) | 任务取消回调（可重写） |
+
+### 属性
+
+| 方法 | 描述 |
+|------|------|
+| [`GetPriority`](getpriority.md) | 获取优先级 |
+| [`GetStatus`](getstatus.md) | 获取状态 |
+| [`GetId`](getid.md) | 获取任务 ID |
+| [`SetId`](setid.md) | 设置任务 ID |
+| [`SetPriority`](setpriority.md) | 设置优先级 |
+| [`SetStatus`](setstatus.md) | 设置状态 |
+
+### 引用计数
+
+| 方法 | 描述 |
+|------|------|
+| [`AddRef`](addref.md) | 增加引用计数 |
+| [`Release`](release.md) | 减少引用计数（引用归零时自动 delete） |
+
+## 使用示例
+
+```cpp
+class MyTask : public ITask {
+public:
+    explicit MyTask(int data) : m_data(data) {}
+    
+    void Execute() override {
+        printf("Task executed with data: %d\n", m_data);
+    }
+    
+    void OnComplete() override {
+        printf("Task completed\n");
+    }
+    
+private:
+    int m_data;
+};
+
+auto task = new MyTask(42);
+task->SetPriority(TaskPriority::High);
+TaskSystem::Get().Submit(std::unique_ptr<ITask>(task));
+```
+
+## 相关文档
+
+- [LambdaTask](../lambdatask/lambdatask.md) - Lambda 任务封装
+- [TaskGroup](../task-group/task-group.md) - 任务组
+- [TaskSystem](../task-system/task-system.md) - 任务系统
+- [../threading/threading.md](../threading.md) - 模块总览