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/debug/logger/addsink.md
+++ b/docs/api/debug/logger/addsink.md
@@ -0,0 +1,27 @@
+# Logger::AddSink
+
+```cpp
+void AddSink(std::unique_ptr<ILogSink> sink)
+```
+
+向日志系统添加一个输出目标（Sink）。Logger 持有 Sink 的所有权，传入的 `unique_ptr` 被移动到内部容器中。每次日志记录时，所有已注册的 Sink 的 `Log` 方法都会被调用。
+
+**参数：**
+- `sink` - 要添加的日志输出目标，使用 `std::unique_ptr` 包装
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Initialize();
+XCEngine::Debug::Logger::Get().AddSink(std::make_unique<XCEngine::Debug::ConsoleLogSink>());
+XCEngine::Debug::Logger::Get().AddSink(std::make_unique<XCEngine::Debug::FileLogSink>("app.log"));
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
+- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口
--- a/docs/api/debug/logger/debug.md
+++ b/docs/api/debug/logger/debug.md
@@ -0,0 +1,30 @@
+# Logger::Debug
+
+```cpp
+void Debug(LogCategory category, const Containers::String& message)
+```
+
+记录一条 Debug（1 级）日志。Debug 级别用于一般调试信息，比 Verbose 简洁但比 Info 详细。
+
+**参数：**
+- `category` - 日志分类
+- `message` - 日志消息内容
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Debug(
+    XCEngine::Debug::LogCategory::Rendering,
+    "Draw call batch size: 512"
+);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
--- a/docs/api/debug/logger/error.md
+++ b/docs/api/debug/logger/error.md
@@ -0,0 +1,30 @@
+# Logger::Error
+
+```cpp
+void Error(LogCategory category, const Containers::String& message)
+```
+
+记录一条 Error（4 级）日志。Error 级别用于表示程序执行中发生的错误，如文件读取失败、网络连接中断等。程序通常可以继续运行但功能可能受限。
+
+**参数：**
+- `category` - 日志分类
+- `message` - 日志消息内容
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Error(
+    XCEngine::Debug::LogCategory::Network,
+    "Failed to connect to game server"
+);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
--- a/docs/api/debug/logger/fatal.md
+++ b/docs/api/debug/logger/fatal.md
@@ -0,0 +1,30 @@
+# Logger::Fatal
+
+```cpp
+void Fatal(LogCategory category, const Containers::String& message)
+```
+
+记录一条 Fatal（5 级）日志。Fatal 级别用于表示不可恢复的严重错误，通常意味着程序即将终止。此方法可能在记录日志后触发程序中断。
+
+**参数：**
+- `category` - 日志分类
+- `message` - 日志消息内容
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Fatal(
+    XCEngine::Debug::LogCategory::General,
+    "Out of memory - cannot continue"
+);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
--- a/docs/api/debug/logger/get.md
+++ b/docs/api/debug/logger/get.md
@@ -0,0 +1,22 @@
+# Logger::Get
+
+```cpp
+static Logger& Get()
+```
+
+获取 `Logger` 单例实例。Logger 使用局部静态变量实现 Meyers' Singleton，确保线程安全且只初始化一次。
+
+**返回：** `Logger&` - 全局日志记录器实例的引用
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+XCEngine::Debug::Logger& logger = XCEngine::Debug::Logger::Get();
+logger.Initialize();
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
--- a/docs/api/debug/logger/info.md
+++ b/docs/api/debug/logger/info.md
@@ -0,0 +1,30 @@
+# Logger::Info
+
+```cpp
+void Info(LogCategory category, const Containers::String& message)
+```
+
+记录一条 Info（2 级）日志。Info 级别用于一般性信息，如启动提示、配置加载等用户可见的正常运行消息。
+
+**参数：**
+- `category` - 日志分类
+- `message` - 日志消息内容
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Info(
+    XCEngine::Debug::LogCategory::General,
+    "Application initialized successfully"
+);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
--- a/docs/api/debug/logger/initialize.md
+++ b/docs/api/debug/logger/initialize.md
@@ -0,0 +1,28 @@
+# Logger::Initialize
+
+```cpp
+void Initialize()
+```
+
+初始化日志系统。在首次使用日志功能前必须调用。初始化内部状态标志，确保日志系统已准备好工作。
+
+**注意：** 默认最小日志级别为 `Verbose`，所有日志分类默认启用，这些是类成员变量的默认值，不需要在此方法中设置。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+int main() {
+    XCEngine::Debug::Logger::Get().Initialize();
+    XCEngine::Debug::Logger::Get().AddSink(std::make_unique<XCEngine::Debug::ConsoleLogSink>());
+    XCEngine::Debug::Logger::Get().Info(XCEngine::Debug::LogCategory::General, "Application started");
+    return 0;
+}
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
--- a/docs/api/debug/logger/log.md
+++ b/docs/api/debug/logger/log.md
@@ -0,0 +1,45 @@
+# Logger::Log
+
+```cpp
+void Log(LogLevel level, LogCategory category,
+         const Containers::String& message, const char* file = nullptr,
+         int32_t line = 0, const char* function = nullptr)
+```
+
+通用日志记录方法。根据设置的最小日志级别和分类开关决定是否输出，然后将日志分发给所有已注册的 Sink。如果日志级别低于最小级别或分类被禁用，则不输出。
+
+**参数：**
+- `level` - 日志级别（Verbose, Debug, Info, Warning, Error, Fatal）
+- `category` - 日志分类（General, Rendering, Physics 等）
+- `message` - 日志消息内容
+- `file` - 源代码文件路径（可选，默认 nullptr）
+- `line` - 源代码行号（可选，默认 0）
+- `function` - 函数名称（可选，默认 nullptr）
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Log(
+    XCEngine::Debug::LogLevel::Error,
+    XCEngine::Debug::LogCategory::FileSystem,
+    "Failed to open config file",
+    __FILE__,
+    __LINE__,
+    __FUNCTION__
+);
+
+// 推荐使用 XE_LOG 宏自动填充位置信息
+XE_LOG(XCEngine::Debug::LogCategory::General, XCEngine::Debug::LogLevel::Info, "Initialized");
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
+- [LogLevel](../loglevel/loglevel.md) - 日志级别枚举
+- [LogCategory](../logcategory/logcategory.md) - 日志分类枚举
--- a/docs/api/debug/logger/logger.md
+++ b/docs/api/debug/logger/logger.md
@@ -0,0 +1,109 @@
+# Logger
+
+**命名空间**: `XCEngine::Debug`
+
+**类型**: `class` (singleton)
+
+**头文件**: `XCEngine/Debug/Logger.h`
+
+**描述**: 全局日志记录器单例，提供多级别、多分类的日志输出。
+
+## 概述
+
+`Logger` 是 XCEngine 的核心日志系统单例。它支持多个日志输出目标（Sink）、日志级别过滤、分类开关，并提供宏方便使用。
+
+## 单例访问
+
+| 方法 | 描述 |
+|------|------|
+| `static Logger& Get()` | 获取单例实例 |
+
+## 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `void Initialize()` | [初始化日志系统](initialize.md) |
+| `void Shutdown()` | [关闭日志系统](shutdown.md) |
+
+### Sink 管理
+
+| 方法 | 描述 |
+|------|------|
+| `void AddSink(std::unique_ptr<ILogSink> sink)` | [添加日志输出目标](addsink.md) |
+| `void RemoveSink(ILogSink* sink)` | [移除日志输出目标](removesink.md) |
+
+### 日志记录
+
+| 方法 | 描述 |
+|------|------|
+| `void Log(...)` | [通用日志记录](log.md) |
+| `void Verbose(...)` | [Verbose 级别日志](verbose.md) |
+| `void Debug(...)` | [Debug 级别日志](debug.md) |
+| `void Info(...)` | [Info 级别日志](info.md) |
+| `void Warning(...)` | [Warning 级别日志](warning.md) |
+| `void Error(...)` | [Error 级别日志](error.md) |
+| `void Fatal(...)` | [Fatal 级别日志](fatal.md) |
+
+### 配置
+
+| 方法 | 描述 |
+|------|------|
+| `void SetMinimumLevel(...)` | [设置最小日志级别](setminimumlevel.md) |
+| `void SetCategoryEnabled(...)` | [开启/关闭指定分类](setcategoryenabled.md) |
+
+## 宏定义
+
+### XE_LOG
+
+```cpp
+#define XE_LOG(category, level, message) \
+    XCEngine::Debug::Logger::Get().Log(level, category, message, __FILE__, __LINE__, __FUNCTION__)
+```
+
+通用日志宏，自动填充文件名、行号和函数名。
+
+### XE_ASSERT
+
+```cpp
+#define XE_ASSERT(condition, message) \
+    if (!(condition)) { \
+        XCEngine::Debug::Logger::Get().Fatal(XCEngine::Debug::LogCategory::General, message); \
+    }
+```
+
+断言宏，条件失败时记录 Fatal 日志。
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+// 初始化
+Logger::Get().Initialize();
+Logger::Get().AddSink(std::make_unique<ConsoleLogSink>());
+Logger::Get().AddSink(std::make_unique<FileLogSink>("app.log"));
+
+// 设置日志级别
+Logger::Get().SetMinimumLevel(LogLevel::Debug);
+
+// 使用便捷方法
+Logger::Get().Info(LogCategory::Rendering, "Render started");
+Logger::Get().Warning(LogCategory::Memory, "High memory usage");
+Logger::Get().Error(LogCategory::FileSystem, "Failed to load file");
+
+// 使用宏（自动带位置信息）
+XE_LOG(LogCategory::General, LogLevel::Info, "Application initialized");
+
+// 使用断言
+XE_ASSERT(ptr != nullptr, "Pointer must not be null");
+```
+
+## 相关文档
+
+- [Debug 模块总览](../debug.md) - 返回模块总览
+- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口
+- [ConsoleLogSink](../consolelogsink/consolelogsink.md) - 控制台输出
+- [FileLogSink](../filelogsink/filelogsink.md) - 文件输出
+- [LogLevel](../loglevel/loglevel.md) - 日志级别枚举
--- a/docs/api/debug/logger/removesink.md
+++ b/docs/api/debug/logger/removesink.md
@@ -0,0 +1,29 @@
+# Logger::RemoveSink
+
+```cpp
+void RemoveSink(ILogSink* sink)
+```
+
+从日志系统移除指定的输出目标。通过指针查找并移除对应的 Sink，Logger 不再向该目标发送日志。
+
+**参数：**
+- `sink` - 要移除的日志输出目标指针
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+auto fileSink = std::make_unique<XCEngine::Debug::FileLogSink>("app.log");
+XCEngine::Debug::FileLogSink* rawPtr = fileSink.get();
+XCEngine::Debug::Logger::Get().AddSink(std::move(fileSink));
+// 稍后移除
+XCEngine::Debug::Logger::Get().RemoveSink(rawPtr);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
+- [ILogSink](../ilogsink/ilogsink.md) - 日志输出接口
--- a/docs/api/debug/logger/setcategoryenabled.md
+++ b/docs/api/debug/logger/setcategoryenabled.md
@@ -0,0 +1,36 @@
+# Logger::SetCategoryEnabled
+
+```cpp
+void SetCategoryEnabled(LogCategory category, bool enabled)
+```
+
+启用或禁用指定分类的日志输出。当分类被禁用时，该分类的所有日志都不会分发给 Sink，但级别过滤仍然适用。
+
+**参数：**
+- `category` - 要设置的日志分类
+- `enabled` - true 表示启用，false 表示禁用
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+// 禁用网络模块日志（减少日志噪音）
+XCEngine::Debug::Logger::Get().SetCategoryEnabled(
+    XCEngine::Debug::LogCategory::Network,
+    false
+);
+
+// 稍后重新启用
+XCEngine::Debug::Logger::Get().SetCategoryEnabled(
+    XCEngine::Debug::LogCategory::Network,
+    true
+);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
+- [LogCategory](../logcategory/logcategory.md) - 日志分类枚举
--- a/docs/api/debug/logger/setminimumlevel.md
+++ b/docs/api/debug/logger/setminimumlevel.md
@@ -0,0 +1,30 @@
+# Logger::SetMinimumLevel
+
+```cpp
+void SetMinimumLevel(LogLevel level)
+```
+
+设置日志系统的最小输出级别。所有低于该级别的日志将被过滤，不会分发给任何 Sink。
+
+**参数：**
+- `level` - 最小日志级别
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+// 只输出 Warning 及以上级别的日志
+XCEngine::Debug::Logger::Get().SetMinimumLevel(XCEngine::Debug::LogLevel::Warning);
+
+// Verbose 和 Debug 级别的日志将被过滤
+XCEngine::Debug::Logger::Get().Verbose(XCEngine::Debug::LogCategory::General, "This will not be logged");
+XCEngine::Debug::Logger::Get().Warning(XCEngine::Debug::LogCategory::General, "This will be logged");
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
+- [LogLevel](../loglevel/loglevel.md) - 日志级别枚举
--- a/docs/api/debug/logger/shutdown.md
+++ b/docs/api/debug/logger/shutdown.md
@@ -0,0 +1,26 @@
+# Logger::Shutdown
+
+```cpp
+void Shutdown()
+```
+
+关闭日志系统。移除所有注册的 Sink，刷新缓冲区并重置内部状态。在程序退出前调用，确保所有日志数据已写入输出目标。
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+int main() {
+    XCEngine::Debug::Logger::Get().Initialize();
+    // ... 应用逻辑 ...
+    XCEngine::Debug::Logger::Get().Shutdown();
+    return 0;
+}
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
--- a/docs/api/debug/logger/verbose.md
+++ b/docs/api/debug/logger/verbose.md
@@ -0,0 +1,30 @@
+# Logger::Verbose
+
+```cpp
+void Verbose(LogCategory category, const Containers::String& message)
+```
+
+记录一条 Verbose（0 级）日志。Verbose 是最详细的日志级别，用于输出大量调试细节。
+
+**参数：**
+- `category` - 日志分类
+- `message` - 日志消息内容
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Verbose(
+    XCEngine::Debug::LogCategory::Memory,
+    "Memory pool fragmentation: 12.5%"
+);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览
--- a/docs/api/debug/logger/warning.md
+++ b/docs/api/debug/logger/warning.md
@@ -0,0 +1,30 @@
+# Logger::Warning
+
+```cpp
+void Warning(LogCategory category, const Containers::String& message)
+```
+
+记录一条 Warning（3 级）日志。Warning 级别用于指示潜在问题但程序仍可继续运行的情况，如资源即将耗尽、配置值超出建议范围等。
+
+**参数：**
+- `category` - 日志分类
+- `message` - 日志消息内容
+
+**返回：** 无
+
+**复杂度：** O(n)，n 为注册的 Sink 数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Debug/Logger.h>
+
+XCEngine::Debug::Logger::Get().Warning(
+    XCEngine::Debug::LogCategory::Memory,
+    "Memory usage exceeds 80% of available heap"
+);
+```
+
+## 相关文档
+
+- [Logger 总览](logger.md) - 返回类总览