fix: improve doc link navigation and tree display

- Fix link resolution with proper relative/absolute path handling - Improve link styling with underline decoration - Hide leaf nodes from tree, only show directories - Fix log file path for packaged app
2026-03-19 12:44:08 +08:00
parent e003fe6513
commit 58a83f445a
1012 changed files with 56880 additions and 22 deletions
--- a/docs/api/threading/task-group/adddependency.md
+++ b/docs/api/threading/task-group/adddependency.md
@@ -0,0 +1,44 @@
+# TaskGroup::AddDependency
+
+```cpp
+void AddDependency(uint64_t taskId, uint64_t dependsOn)
+```
+
+为任务添加依赖关系。被依赖的任务必须先完成，当前任务才会开始执行。
+
+**参数：**
+- `taskId` - 任务 ID（需要等待的任务）
+- `dependsOn` - 依赖的父任务 ID
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**注意：**
+- 如果被依赖的任务不存在或已完成，调用无效果。
+- 支持添加多个依赖，但不支持循环依赖。
+
+**示例：**
+
+```cpp
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+
+uint64_t init = group->AddTask([]() { Initialize(); });
+uint64_t task1 = group->AddTask([]() { Phase1(); });
+uint64_t task2 = group->AddTask([]() { Phase2(); });
+uint64_t cleanup = group->AddTask([]() { Cleanup(); });
+
+// task1 和 task2 依赖 init
+group->AddDependency(task1, init);
+group->AddDependency(task2, init);
+
+// cleanup 依赖 task1 和 task2
+group->AddDependency(cleanup, task1);
+group->AddDependency(cleanup, task2);
+
+group->Wait();
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 返回类总览
--- a/docs/api/threading/task-group/addtask.md
+++ b/docs/api/threading/task-group/addtask.md
@@ -0,0 +1,60 @@
+# TaskGroup::AddTask
+
+添加任务到任务组。有两个重载版本。
+
+## 重载 1: 添加 ITask 对象
+
+```cpp
+uint64_t AddTask(std::unique_ptr<ITask> task)
+```
+
+将一个已有的 ITask 对象添加到任务组。
+
+**参数：**
+- `task` - 要添加的 unique_ptr 任务对象
+
+**返回：** `uint64_t` - 分配的任务 ID
+
+**复杂度：** O(1)
+
+## 重载 2: 添加 lambda 任务
+
+```cpp
+uint64_t AddTask(Callback&& func, TaskPriority priority = TaskPriority::Normal)
+```
+
+将一个 lambda 函数包装为任务添加到任务组。
+
+**参数：**
+- `func` - 要执行的可调用对象
+- `priority` - 任务优先级，默认 TaskPriority::Normal
+
+**返回：** `uint64_t` - 分配的任务 ID
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+
+// 添加 lambda 任务
+uint64_t id1 = group->AddTask([]() {
+    printf("Task A running\n");
+});
+
+uint64_t id2 = group->AddTask([]() {
+    printf("Task B running\n");
+}, TaskPriority::High);
+
+// 添加自定义 ITask
+class MyTask : public ITask {
+public:
+    void Execute() override { printf("Custom task\n"); }
+};
+uint64_t id3 = group->AddTask(std::make_unique<MyTask>());
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 返回类总览
--- a/docs/api/threading/task-group/cancel.md
+++ b/docs/api/threading/task-group/cancel.md
@@ -0,0 +1,45 @@
+# TaskGroup::Cancel
+
+```cpp
+void Cancel()
+```
+
+**注意：** 此方法为**部分实现**，存在已知问题。
+
+取消任务组中所有尚未执行的任务。正在执行的任务将不受影响。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(n)
+
+**当前状态：** 此方法会调用各任务的 `OnCancel()` 回调，但不会减少 `m_pendingCount` 计数器。因此调用 `Wait()` 会导致永久阻塞。建议在 `Cancel()` 后使用 `IsComplete()` 轮询或使用带超时的 `WaitFor()`。
+
+**示例：**
+
+```cpp
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+
+for (int i = 0; i < 100; ++i) {
+    group->AddTask([i]() {
+        if (ShouldCancel()) {
+            return; // 检查取消状态
+        }
+        ProcessLongTask(i);
+    });
+}
+
+// 如果用户点击取消按钮
+if (userClickedCancel) {
+    group->Cancel();
+    printf("Tasks canceled. Progress: %.1f%%\n", group->GetProgress() * 100.0f);
+}
+
+// 注意：Cancel() 后 Wait() 会永久阻塞，应使用 WaitFor()
+group->WaitFor(std::chrono::seconds(1));
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 返回类总览
--- a/docs/api/threading/task-group/getprogress.md
+++ b/docs/api/threading/task-group/getprogress.md
@@ -0,0 +1,40 @@
+# TaskGroup::GetProgress
+
+```cpp
+float GetProgress() const
+```
+
+**注意：** 此方法当前为**空实现/桩代码**。
+
+获取任务组的完成进度。
+
+**参数：** 无
+
+**返回：** `float` - 始终返回 `0.0f`（任务组为空时返回 `1.0f`）
+
+**复杂度：** O(1)
+
+**当前状态：** 此方法为空实现，始终返回 `0.0f`，因为 `m_completedCount` 未被更新。
+
+**示例：**
+
+```cpp
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+
+for (int i = 0; i < 1000; ++i) {
+    group->AddTask([i]() { ProcessItem(i); });
+}
+
+// 显示进度（注意：当前实现始终返回 0.0f）
+while (!group->IsComplete()) {
+    float progress = group->GetProgress();
+    printf("\rProgress: %.1f%%", progress * 100.0f);
+    Thread::Sleep(100);
+}
+printf("\n");
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 返回类总览
+- [IsComplete](iscomplete.md) - 检查是否完成
--- a/docs/api/threading/task-group/iscomplete.md
+++ b/docs/api/threading/task-group/iscomplete.md
@@ -0,0 +1,38 @@
+# TaskGroup::IsComplete
+
+```cpp
+bool IsComplete() const
+```
+
+**注意：** 此方法当前为**空实现/桩代码**。
+
+检查任务组中所有任务是否已完成。
+
+**参数：** 无
+
+**返回：** `bool` - 始终返回 `false`（空实现）
+
+**复杂度：** O(1)（空实现）
+
+**当前状态：** 此方法为空实现，始终返回 `false`，因为 `m_pendingCount` 计数器未正确递减。
+
+**示例：**
+
+```cpp
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+
+for (int i = 0; i < 100; ++i) {
+    group->AddTask([i]() { HeavyCompute(i); });
+}
+
+// 非阻塞轮询
+while (!group->IsComplete()) {
+    printf("Progress: %.1f%%\n", group->GetProgress() * 100.0f);
+    Thread::Sleep(500);
+}
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 返回类总览
+- [GetProgress](getprogress.md) - 获取完成进度
--- a/docs/api/threading/task-group/setcompletecallback.md
+++ b/docs/api/threading/task-group/setcompletecallback.md
@@ -0,0 +1,36 @@
+# TaskGroup::SetCompleteCallback
+
+```cpp
+void SetCompleteCallback(Callback&& callback)
+```
+
+设置任务组完成回调。当所有任务都完成后，回调函数将在某个工作线程中被调用。
+
+**参数：**
+- `callback` - 完成时要调用的回调函数
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+
+group->AddTask([]() { LoadTextures(); });
+group->AddTask([]() { LoadMeshes(); });
+group->AddTask([]() { LoadAudio(); });
+
+group->SetCompleteCallback([]() {
+    printf("All assets loaded!\n");
+    ResourceManager::InitGPUResources();
+});
+
+group->Wait();
+TaskSystem::Get().DestroyTaskGroup(group);
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 返回类总览
--- a/docs/api/threading/task-group/task-group.md
+++ b/docs/api/threading/task-group/task-group.md
@@ -0,0 +1,66 @@
+# TaskGroup
+
+**命名空间**: `XCEngine::Threading`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Threading/TaskGroup.h`
+
+**描述**: 任务组管理类，用于组织多个任务并支持批量等待、进度跟踪和依赖管理。
+
+## 概述
+
+`TaskGroup` 提供了一种批量管理任务的机制。它允许添加多个任务、设置任务依赖关系、等待所有任务完成，并提供进度回调功能。
+
+## 公共类型
+
+| 类型 | 描述 |
+|------|------|
+| `Callback = std::function<void()>` | 任务组回调函数类型 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `TaskGroup()` | 默认构造函数 |
+| `~TaskGroup()` | 析构函数 |
+| [`AddTask(unique_ptr)`](addtask.md) | 添加任务对象 |
+| [`AddTask(callback)`](addtask.md) | 添加 lambda 任务 |
+| [`AddDependency`](adddependency.md) | 添加任务依赖关系 |
+| [`Wait`](wait.md) | 阻塞等待所有任务完成 |
+| [`WaitFor`](waitfor.md) | 超时等待 |
+| [`SetCompleteCallback`](setcompletecallback.md) | 设置完成回调 |
+| [`IsComplete`](iscomplete.md) | 检查所有任务是否完成 |
+| [`GetProgress`](getprogress.md) | 获取完成进度（0.0f ~ 1.0f） |
+| [`Cancel`](cancel.md) | 取消所有任务 |
+
+## 使用示例
+
+```cpp
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+
+// 添加多个任务
+uint64_t task1 = group->AddTask([]() { /* 任务1 */ });
+uint64_t task2 = group->AddTask([]() { /* 任务2 */ });
+
+// 设置依赖：task3 等待 task1 完成
+uint64_t task3 = group->AddTask([]() { /* 任务3 */ });
+group->AddDependency(task3, task1);
+
+// 设置完成回调
+group->SetCompleteCallback([]() {
+    printf("All tasks completed!\n");
+});
+
+// 等待完成
+group->Wait();
+
+// 销毁
+TaskSystem::Get().DestroyTaskGroup(group);
+```
+
+## 相关文档
+
+- [ITask](../task/task.md) - 任务基类
+- [TaskSystem](../task-system/task-system.md) - 任务系统
+- [../threading/threading.md](../threading.md) - 模块总览
--- a/docs/api/threading/task-group/wait.md
+++ b/docs/api/threading/task-group/wait.md
@@ -0,0 +1,46 @@
+# TaskGroup::Wait
+
+```cpp
+void Wait()
+```
+
+**注意：** 此方法当前为**空实现/桩代码**，不执行任何操作。
+
+阻塞当前线程，等待任务组中所有任务完成。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** N/A（空实现）
+
+**当前状态：** 此方法为空实现，不执行任何操作。由于 `m_pendingCount` 计数器未正确更新，此方法永远无法正常运作。
+
+**建议：** 使用 `WaitFor()` 代替以避免永久阻塞。
+
+**示例：**
+
+```cpp
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+
+for (int i = 0; i < 10; ++i) {
+    group->AddTask([i]() {
+        printf("Task %d running\n", i);
+    });
+}
+
+printf("Waiting for all tasks...\n");
+// 注意：Wait() 为空实现，建议使用 WaitFor()
+if (group->WaitFor(std::chrono::seconds(5))) {
+    printf("All tasks completed within 5 seconds\n");
+} else {
+    printf("Timeout! Tasks may not have completed\n");
+}
+
+TaskSystem::Get().DestroyTaskGroup(group);
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 返回类总览
+- [WaitFor](waitfor.md) - 超时等待
--- a/docs/api/threading/task-group/waitfor.md
+++ b/docs/api/threading/task-group/waitfor.md
@@ -0,0 +1,39 @@
+# TaskGroup::WaitFor
+
+```cpp
+bool WaitFor(std::chrono::milliseconds timeout)
+```
+
+等待任务组中所有任务完成，可在超时后返回。
+
+**参数：**
+- `timeout` - 最大等待时间
+
+**返回：** `bool` - 所有任务在超时前完成返回 true，超时返回 false
+
+**复杂度：** O(n)
+
+**示例：**
+
+```cpp
+TaskGroup* group = TaskSystem::Get().CreateTaskGroup();
+
+for (int i = 0; i < 5; ++i) {
+    group->AddTask([i]() {
+        Thread::Sleep(i * 100);
+        printf("Task %d done\n", i);
+    });
+}
+
+if (group->WaitFor(std::chrono::seconds(1))) {
+    printf("All tasks completed within 1 second\n");
+} else {
+    printf("Timeout! Some tasks still running\n");
+    printf("Progress: %.1f%%\n", group->GetProgress() * 100.0f);
+}
+```
+
+## 相关文档
+
+- [TaskGroup 总览](task-group.md) - 返回类总览
+- [Wait](wait.md) - 无超时等待