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/resources/dependencygraph/adddependency.md
+++ b/docs/api/resources/dependencygraph/adddependency.md
@@ -0,0 +1,27 @@
+# ResourceDependencyGraph::AddDependency
+
+```cpp
+void AddDependency(ResourceGUID owner, ResourceGUID dependency)
+```
+
+添加资源依赖关系。表示 `owner` 资源依赖 `dependency` 资源。依赖关系是单向的。
+
+**参数：**
+- `owner` - 拥有依赖关系的主体资源
+- `dependency` - 被依赖的资源
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+// Material 依赖 Texture 和 Shader
+graph.AddDependency(materialGuid, textureGuid);
+graph.AddDependency(materialGuid, shaderGuid);
+```
+
+## 相关文档
+
+- [ResourceDependencyGraph 总览](dependencygraph.md) - 返回类总览
--- a/docs/api/resources/dependencygraph/addnode.md
+++ b/docs/api/resources/dependencygraph/addnode.md
@@ -0,0 +1,27 @@
+# ResourceDependencyGraph::AddNode
+
+```cpp
+void AddNode(ResourceGUID guid, ResourceType type)
+```
+
+向依赖图中添加一个新节点。如果节点已存在则忽略。
+
+**参数：**
+- `guid` - 资源的全局唯一标识符
+- `type` - 资源类型
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceDependencyGraph graph;
+graph.AddNode(textureGuid, ResourceType::Texture);
+graph.AddNode(materialGuid, ResourceType::Material);
+```
+
+## 相关文档
+
+- [ResourceDependencyGraph 总览](dependencygraph.md) - 返回类总览
--- a/docs/api/resources/dependencygraph/dependencygraph.md
+++ b/docs/api/resources/dependencygraph/dependencygraph.md
@@ -0,0 +1,111 @@
+# ResourceDependencyGraph
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class`
+
+**描述**: 资源依赖图管理器，负责跟踪资源之间的依赖关系、引用计数和拓扑排序。
+
+## 概述
+
+`ResourceDependencyGraph` 维护了所有资源之间的依赖关系图。它支持添加/移除依赖节点、查询依赖关系、循环依赖检测、拓扑排序（用于正确的加载/卸载顺序）等功能。
+
+## DependencyNode 结构体
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `guid` | `ResourceGUID` | 资源全局唯一标识符 |
+| `type` | `ResourceType` | 资源类型 |
+| `dependencies` | `Containers::Array<ResourceGUID>` | 此资源依赖的其他资源 |
+| `dependents` | `Containers::Array<ResourceGUID>` | 依赖此资源的其他资源 |
+| `refCount` | `Core::uint32` | 引用计数 |
+
+## 公共方法
+
+### 节点管理
+
+| 方法 | 描述 |
+|------|------|
+| `void AddNode(ResourceGUID guid, ResourceType type)` | 添加依赖节点 |
+| `void RemoveNode(ResourceGUID guid)` | 移除依赖节点 |
+| `bool HasNode(ResourceGUID guid) const` | 检查节点是否存在 |
+
+### 依赖关系
+
+| 方法 | 描述 |
+|------|------|
+| `void AddDependency(ResourceGUID owner, ResourceGUID dependency)` | 添加依赖关系（A 依赖 B） |
+| `void RemoveDependency(ResourceGUID owner, ResourceGUID dependency)` | 移除依赖关系 |
+| `Containers::Array<ResourceGUID> GetDependencies(ResourceGUID guid) const` | 获取指定资源的直接依赖列表 |
+| `Containers::Array<ResourceGUID> GetDependents(ResourceGUID guid) const` | 获取依赖指定资源的所有资源列表 |
+| `Containers::Array<ResourceGUID> GetAllDependencies(ResourceGUID guid) const` | 获取所有递归依赖（包括传递依赖） |
+
+### 引用计数
+
+| 方法 | 描述 |
+|------|------|
+| `void IncrementRefCount(ResourceGUID guid)` | 增加引用计数 |
+| `void DecrementRefCount(ResourceGUID guid)` | 减少引用计数 |
+| `Core::uint32 GetRefCount(ResourceGUID guid) const` | 获取引用计数 |
+
+### 循环检测
+
+| 方法 | 描述 |
+|------|------|
+| `bool HasCircularDependency(ResourceGUID guid, Containers::Array<ResourceGUID>& outCycle) const` | 检测是否存在循环依赖 |
+
+### 排序与卸载
+
+| 方法 | 描述 |
+|------|------|
+| `Containers::Array<ResourceGUID> TopologicalSort() const` | 拓扑排序（按依赖顺序） |
+| `bool Unload(ResourceGUID guid)` | 安全卸载（考虑依赖关系） |
+
+### 清理
+
+| 方法 | 描述 |
+|------|------|
+| `void Clear()` | 清空所有节点和依赖关系 |
+
+## 使用示例
+
+```cpp
+ResourceDependencyGraph graph;
+
+// 添加节点
+graph.AddNode(textureGuid, ResourceType::Texture);
+graph.AddNode(materialGuid, ResourceType::Material);
+graph.AddNode(shaderGuid, ResourceType::Shader);
+
+// 设置依赖关系：Material 依赖 Texture 和 Shader
+graph.AddDependency(materialGuid, textureGuid);
+graph.AddDependency(materialGuid, shaderGuid);
+
+// 查询依赖
+auto deps = graph.GetDependencies(materialGuid);
+// deps 包含 textureGuid 和 shaderGuid
+
+// 查询被依赖者
+auto dependents = graph.GetDependents(textureGuid);
+// dependents 包含 materialGuid
+
+// 拓扑排序（正确的加载顺序）
+auto loadOrder = graph.TopologicalSort();
+// loadOrder 保证依赖在目标之前加载
+
+// 循环依赖检测
+Containers::Array<ResourceGUID> cycle;
+if (graph.HasCircularDependency(guid, cycle)) {
+    printf("Circular dependency detected!");
+}
+
+// 引用计数
+graph.IncrementRefCount(guid);
+graph.DecrementRefCount(guid);
+```
+
+## 相关文档
+
+- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
+- [ResourceHandle](../resourcehandle/resourcehandle.md) - 资源句柄
+- [Resources 总览](../resources.md) - 返回模块总览
--- a/docs/api/resources/dependencygraph/getdependencies.md
+++ b/docs/api/resources/dependencygraph/getdependencies.md
@@ -0,0 +1,25 @@
+# ResourceDependencyGraph::GetDependencies
+
+```cpp
+Containers::Array<ResourceGUID> GetDependencies(ResourceGUID guid) const
+```
+
+获取指定资源直接依赖的所有资源列表。不包含传递依赖。
+
+**参数：**
+- `guid` - 资源全局唯一标识符
+
+**返回：** 直接依赖的 GUID 数组
+
+**复杂度：** O(k)，k 为直接依赖数量
+
+**示例：**
+
+```cpp
+auto deps = graph.GetDependencies(materialGuid);
+// 返回 Material 直接依赖的资源（Texture、Shader 等）
+```
+
+## 相关文档
+
+- [ResourceDependencyGraph 总览](dependencygraph.md) - 返回类总览
--- a/docs/api/resources/dependencygraph/hascirculardependency.md
+++ b/docs/api/resources/dependencygraph/hascirculardependency.md
@@ -0,0 +1,31 @@
+# ResourceDependencyGraph::HasCircularDependency
+
+```cpp
+bool HasCircularDependency(ResourceGUID guid, Containers::Array<ResourceGUID>& outCycle) const
+```
+
+检测是否存在以指定节点为起点的循环依赖。使用 DFS 遍历依赖图，检测回路。
+
+**参数：**
+- `guid` - 起始节点
+- `outCycle` - 输出参数，检测到的循环路径（包含形成环的节点 GUID）
+
+**返回：** 如果存在循环依赖则返回 true，否则返回 false
+
+**复杂度：** O(n + e)
+
+**示例：**
+
+```cpp
+Containers::Array<ResourceGUID> cycle;
+if (graph.HasCircularDependency(guid, cycle)) {
+    printf("Circular dependency detected: ");
+    for (const auto& g : cycle) {
+        printf("%llu ", g.value);
+    }
+}
+```
+
+## 相关文档
+
+- [ResourceDependencyGraph 总览](dependencygraph.md) - 返回类总览
--- a/docs/api/resources/dependencygraph/topologicalsort.md
+++ b/docs/api/resources/dependencygraph/topologicalsort.md
@@ -0,0 +1,28 @@
+# ResourceDependencyGraph::TopologicalSort
+
+```cpp
+Containers::Array<ResourceGUID> TopologicalSort() const
+```
+
+拓扑排序。按依赖顺序返回所有节点，确保被依赖的资源排在依赖者之前。用于确定正确的加载和卸载顺序。
+
+**参数：** 无
+
+**返回：** 按依赖顺序排序的 GUID 数组
+
+**复杂度：** O(n + e)，n 为节点数，e 为边数
+
+**示例：**
+
+```cpp
+auto loadOrder = graph.TopologicalSort();
+// loadOrder[0] 是最底层依赖（如 Texture）
+// loadOrder[last] 是最顶层资源（如 Material）
+for (const auto& guid : loadOrder) {
+    ResourceManager::Get().Load(guid);
+}
+```
+
+## 相关文档
+
+- [ResourceDependencyGraph 总览](dependencygraph.md) - 返回类总览