docs: rebuild Threading API content

docs/api/XCEngine/Threading/TaskGroup/TaskGroup.md

@@ -6,34 +6,58 @@
 
 **头文件**: `XCEngine/Threading/TaskGroup.h`
 
-**描述**: 定义 `XCEngine/Threading` 子目录中的 `TaskGroup` public API。
+**描述**: 表示一组带依赖关系的任务集合，目标是为任务批次提供等待、进度查询和完成回调入口。
 
 ## 概述
 
-`TaskGroup.h` 是 `XCEngine/Threading` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`TaskGroup` 体现的是商业引擎里很常见的一个设计方向: 把一批相关任务组织成一个“组”，然后围绕这批任务暴露：
 
-## 声明概览
+- 批量添加任务。
+- 任务之间的依赖关系。
+- 整组完成等待。
+- 整组完成回调。
+- 进度查询与取消。
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `TaskGroup` | `class` | 头文件中的公开声明。 |
+这种抽象本身是合理的。像 Unity 的 job fence、Unreal 的 task graph event，以及很多自研引擎里的 batch/fence/group 概念，本质上都在解决同一个问题: 上层系统往往关心“一批工作什么时候整体完成”，而不是只关心单个任务对象。
 
-## 公共方法
+## 当前实现边界
 
-| 方法 | 描述 |
+当前 `TaskGroup` 还停留在骨架阶段，文档必须按源码现实理解：
+
+- [AddTask](AddTask.md) 会把 `std::unique_ptr<ITask>` 释放成裸指针保存，但析构函数是默认实现，当前不会回收这些任务对象。
+- [AddDependency](AddDependency.md) 只记录依赖 ID，不会更新 `pendingDepCount`，也没有真正接入调度流程。
+- [Wait](Wait.md) 和 [WaitFor](WaitFor.md) 依赖 `m_pendingCount == 0`，但当前代码里这个计数只增不减。
+- [GetProgress](GetProgress.md) 依赖 `m_completedCount`，但当前没有任何路径会递增它。
+- [SetCompleteCallback](SetCompleteCallback.md) 只是保存回调，当前不会触发。
+- [Cancel](Cancel.md) 只会调用 `OnCancel()`，不会让任务组进入“已完成”状态，也不会唤醒等待者。
+- 当前 `TaskGroup` 和 [TaskSystem](../TaskSystem/TaskSystem.md) 之间没有形成真正的组调度联动。
+
+因此，当前源码中的 `TaskGroup` 更像“未来任务图系统的接口草图”，而不是已经可依赖的完成态任务栅栏。
+
+## 公开方法
+
+| 方法 | 说明 |
 |------|------|
-| [TaskGroup()](Constructor.md) | 构造对象。 |
-| [~TaskGroup()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [AddTask](AddTask.md) | 添加元素或建立关联。 |
-| [AddDependency](AddDependency.md) | 添加元素或建立关联。 |
-| [Wait](Wait.md) | 公开方法，详见头文件声明。 |
-| [WaitFor](WaitFor.md) | 公开方法，详见头文件声明。 |
-| [SetCompleteCallback](SetCompleteCallback.md) | 设置相关状态或配置。 |
-| [IsComplete](IsComplete.md) | 查询当前状态。 |
-| [GetProgress](GetProgress.md) | 获取相关状态或对象。 |
-| [Cancel](Cancel.md) | 判断当前条件下是否可执行。 |
+| [Constructor](Constructor.md) | 构造一个空任务组。 |
+| [Destructor](Destructor.md) | 销毁任务组对象。 |
+| [AddTask](AddTask.md) | 向任务组添加一个任务或 lambda。 |
+| [AddDependency](AddDependency.md) | 为任务记录依赖关系。 |
+| [Wait](Wait.md) | 阻塞等待任务组完成。 |
+| [WaitFor](WaitFor.md) | 限时等待任务组完成。 |
+| [SetCompleteCallback](SetCompleteCallback.md) | 设置完成回调。 |
+| [IsComplete](IsComplete.md) | 查询任务组是否完成。 |
+| [GetProgress](GetProgress.md) | 查询完成进度。 |
+| [Cancel](Cancel.md) | 取消任务组中的未完成任务。 |
+
+## 使用建议
+
+- 如果你现在需要稳定的并发基础设施，优先使用 [Mutex](../Mutex/Mutex.md)、[SpinLock](../SpinLock/SpinLock.md)、[ReadWriteLock](../ReadWriteLock/ReadWriteLock.md) 和 [Thread](../Thread/Thread.md)。
+- 当前不要把 `TaskGroup` 当成可用的 task fence 或 job dependency graph。
+- 如果后续要把它做成商用级任务组，至少需要补齐任务所有权、依赖计数、完成通知和 `TaskSystem` 集成。
 
 ## 相关文档
 
-- [当前目录](../Threading.md) - 返回 `Threading` 平行目录
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [当前模块](../Threading.md)
+- [ITask](../Task/Task.md)
+- [TaskSystem](../TaskSystem/TaskSystem.md)
+- [Synchronization And Task System Limits](../../../_guides/Threading/Synchronization-And-TaskSystem-Limits.md)