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/core/core.md
+++ b/docs/api/core/core.md
@@ -0,0 +1,97 @@
+# Core 模块概览
+
+**命名空间**: `XCEngine::Core`
+
+**类型**: `module`
+
+**描述**: XCEngine 的核心基础模块，提供类型别名、智能指针、事件系统等基础功能。
+
+## 概述
+
+Core 模块包含了引擎所需的基础类型和工具，是其他所有模块的依赖基础。
+
+## 模块内容
+
+### 类型
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Types](types/types.md) | `Types.h` | 类型别名定义 |
+
+### 智能指针
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [SmartPtr](smartptr/smartptr.md) | `SmartPtr.h` | 智能指针别名和工厂函数 |
+| [RefCounted](refcounted/refcounted.md) | `RefCounted.h` | 引用计数基类 |
+
+### 事件系统
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [Event](event/event.md) | `Event.h` | 事件系统模板 |
+
+### 文件操作
+
+| 组件 | 文件 | 描述 |
+|------|------|------|
+| [FileWriter](filewriter/filewriter.md) | `FileWriter.h` | 文件写入工具 |
+
+## 类型别名
+
+```cpp
+using int8 = int8_t;
+using int16 = int16_t;
+using int32 = int32_t;
+using int64 = int64_t;
+using uint8 = uint8_t;
+using uint16 = uint16_t;
+using uint32 = uint32_t;
+using uint64 = uint64_t;
+using byte = uint8_t;
+```
+
+## 智能指针别名
+
+```cpp
+template<typename T>
+using Ref = std::shared_ptr<T>;
+
+template<typename T>
+using UniqueRef = std::unique_ptr<T>;
+
+template<typename T, typename... Args>
+Ref<T> MakeRef(Args&&... args);
+
+template<typename T, typename... Args>
+UniqueRef<T> MakeUnique(Args&&... args);
+```
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Core/Core.h>
+#include <XCEngine/Containers/String.h>
+
+using namespace XCEngine::Core;
+
+// 使用类型别名
+uint32 value = 100;
+byte data[4];
+
+// 使用智能指针
+auto ref = MakeRef<MyClass>();
+auto unique = MakeUnique<MyClass>();
+
+// 使用事件系统
+Event<int, float> myEvent;
+myEvent.Subscribe([](int a, float b) {
+    printf("Event: %d, %f\n", a, b);
+});
+myEvent.Invoke(42, 3.14f);
+```
+
+## 相关文档
+
+- [Containers 模块](../containers/containers.md) - 容器类型
+- [Memory 模块](../memory/memory.md) - 内存管理
--- a/docs/api/core/event/Clear.md
+++ b/docs/api/core/event/Clear.md
@@ -0,0 +1,39 @@
+# Event::Clear
+
+```cpp
+void Clear();
+```
+
+清空所有订阅。
+
+**描述**
+
+移除所有已订阅的回调，清空事件。线程安全。
+
+**复杂度：** O(n) 其中 n 为订阅数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+Event<int> event;
+
+// 订阅多个回调
+event.Subscribe([](int v) { });
+event.Subscribe([](int v) { });
+event.Subscribe([](int v) { });
+
+// 清空所有订阅
+event.Clear();
+
+// 触发（无回调被执行）
+event.Invoke(42);
+```
+
+## 相关文档
+
+- [Event 总览](event.md) - 返回类总览
+- [Unsubscribe](Unsubscribe.md) - 退订单个事件
--- a/docs/api/core/event/Invoke.md
+++ b/docs/api/core/event/Invoke.md
@@ -0,0 +1,45 @@
+# Event::Invoke
+
+```cpp
+void Invoke(Args... args);
+```
+
+调用所有订阅的回调。
+
+**描述**
+
+依次调用所有已订阅的回调函数。在调用前会自动处理待退订的回调。回调是在锁外执行的，因此可以在回调中安全地进行订阅/退订操作。线程安全。
+
+**参数：**
+- `args` - 传递给回调的参数
+
+**复杂度：** O(n) 其中 n 为订阅数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+// 无参数事件
+Event<> frameEndEvent;
+frameEndEvent.Subscribe([]() {
+    printf("Frame ended\n");
+});
+
+// 带参数事件
+Event<int, const char*> playerDiedEvent;
+playerDiedEvent.Subscribe([](int playerId, const char* reason) {
+    printf("Player %d died: %s\n", playerId, reason);
+});
+
+// 触发事件
+frameEndEvent.Invoke();
+playerDiedEvent.Invoke(1, "fell off a cliff");
+```
+
+## 相关文档
+
+- [Event 总览](event.md) - 返回类总览
+- [Subscribe](Subscribe.md) - 订阅事件
--- a/docs/api/core/event/ProcessUnsubscribes.md
+++ b/docs/api/core/event/ProcessUnsubscribes.md
@@ -0,0 +1,39 @@
+# Event::ProcessUnsubscribes
+
+```cpp
+void ProcessUnsubscribes();
+```
+
+处理积压的退订请求。
+
+**描述**
+
+手动处理待退订的回调，将其从订阅列表中移除。通常不需要手动调用，`Invoke` 会自动处理退订。但在某些场景下可能需要主动调用。
+
+**复杂度：** O(n) 其中 n 为待退订数量
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+Event<int> event;
+
+// 订阅
+uint64_t id = event.Subscribe([](int value) { });
+
+// 退订请求入队
+event.Unsubscribe(id);
+
+// 主动处理退订
+event.ProcessUnsubscribes();
+
+// 此时事件列表中已无该回调
+```
+
+## 相关文档
+
+- [Event 总览](event.md) - 返回类总览
+- [Unsubscribe](Unsubscribe.md) - 退订事件
--- a/docs/api/core/event/Subscribe.md
+++ b/docs/api/core/event/Subscribe.md
@@ -0,0 +1,50 @@
+# Event::Subscribe
+
+```cpp
+uint64_t Subscribe(Callback callback);
+```
+
+订阅事件回调。
+
+**描述**
+
+将回调函数添加到事件订阅列表中，并返回一个唯一的订阅 ID。该 ID 可用于后续退订。线程安全，可在任意线程调用。
+
+**参数：**
+- `callback` - 要订阅的回调函数，类型为 `std::function<void(Args...)>`
+
+**返回：** `uint64_t` - 订阅 ID，用于退订
+
+**复杂度：** O(1) amortized
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+// 定义事件
+Event<int, float> damageEvent;
+
+// 订阅多个回调
+uint64_t id1 = damageEvent.Subscribe([](int damage, float time) {
+    printf("Damage taken: %d at time %f\n", damage, time);
+});
+
+uint64_t id2 = damageEvent.Subscribe([](int damage, float time) {
+    // 记录伤害日志
+});
+
+// 使用 lambda 表达式
+auto callback = [](int damage, float time) {
+    // 处理伤害
+};
+uint64_t id3 = damageEvent.Subscribe(callback);
+```
+
+## 相关文档
+
+- [Event 总览](event.md) - 返回类总览
+- [Unsubscribe](Unsubscribe.md) - 退订事件
+- [Invoke](Invoke.md) - 触发事件
--- a/docs/api/core/event/Unsubscribe.md
+++ b/docs/api/core/event/Unsubscribe.md
@@ -0,0 +1,43 @@
+# Event::Unsubscribe
+
+```cpp
+void Unsubscribe(uint64_t id);
+```
+
+退订事件。
+
+**描述**
+
+将指定 ID 的回调从订阅列表中移除。退订是延迟生效的，在调用 `Invoke` 时会一并处理待退订的回调。线程安全，可在任意线程调用。
+
+**参数：**
+- `id` - 订阅时返回的 ID
+
+**复杂度：** O(n) 在 Invoke 时处理
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+Event<int> someEvent;
+
+// 订阅
+uint64_t id = someEvent.Subscribe([](int value) {
+    printf("Value: %d\n", value);
+});
+
+// 退订
+someEvent.Unsubscribe(id);
+
+// 触发（已退订的回调不会被调用）
+someEvent.Invoke(42);
+```
+
+## 相关文档
+
+- [Event 总览](event.md) - 返回类总览
+- [Subscribe](Subscribe.md) - 订阅事件
+- [ProcessUnsubscribes](ProcessUnsubscribes.md) - 手动处理退订
--- a/docs/api/core/event/begin.md
+++ b/docs/api/core/event/begin.md
@@ -0,0 +1,37 @@
+# Event::begin
+
+```cpp
+Iterator begin();
+```
+
+获取开始迭代器。
+
+**描述**
+
+返回订阅列表的开始迭代器，用于范围for循环遍历所有订阅的回调。
+
+**返回：** `Iterator` - 指向第一个监听器的迭代器（等价于 `std::vector<Listener>::iterator`）
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+Event<int> event;
+event.Subscribe([](int v) { printf("Callback 1: %d\n", v); });
+event.Subscribe([](int v) { printf("Callback 2: %d\n", v); });
+
+// 遍历所有订阅
+for (auto& [id, callback] : event) {
+    callback(100);
+}
+```
+
+## 相关文档
+
+- [Event 总览](event.md) - 返回类总览
+- [end](end.md) - 获取结束迭代器
--- a/docs/api/core/event/end.md
+++ b/docs/api/core/event/end.md
@@ -0,0 +1,36 @@
+# Event::end
+
+```cpp
+Iterator end();
+```
+
+获取结束迭代器。
+
+**描述**
+
+返回订阅列表的结束迭代器，用于范围for循环遍历所有订阅的回调。
+
+**返回：** `Iterator` - 指向末尾的迭代器（等价于 `std::vector<Listener>::iterator`）
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+Event<int> event;
+event.Subscribe([](int v) { printf("Callback: %d\n", v); });
+
+// 遍历所有订阅
+for (auto& [id, callback] : event) {
+    callback(42);
+}
+```
+
+## 相关文档
+
+- [Event 总览](event.md) - 返回类总览
+- [begin](begin.md) - 获取开始迭代器
--- a/docs/api/core/event/event.md
+++ b/docs/api/core/event/event.md
@@ -0,0 +1,69 @@
+# Event
+
+**命名空间**: `XCEngine::Core`
+
+**类型**: `class` (template)
+
+**描述**: 事件系统模板类，提供类型安全的多订阅者事件/委托系统。
+
+## 概述
+
+`Event<Args...>` 是一个类型安全的事件发布-订阅系统。它支持多个回调订阅、退订和线程安全的调用。非常适合用于游戏引擎中的事件驱动通信。
+
+## 模板参数
+
+| 参数 | 描述 |
+|------|------|
+| `Args...` | 事件回调的参数类型 |
+
+## 类型别名
+
+| 别名 | 类型 | 描述 |
+|------|------|------|
+| `Callback` | `std::function<void(Args...)>` | 回调函数类型 |
+| `Listener` | `std::pair<uint64_t, Callback>` | 监听器条目 |
+| `Iterator` | `std::vector<Listener>::iterator` | 迭代器类型 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [`Subscribe`](Subscribe.md) | 订阅事件回调，返回订阅 ID |
+| [`Unsubscribe`](Unsubscribe.md) | 退订事件（延迟生效） |
+| [`ProcessUnsubscribes`](ProcessUnsubscribes.md) | 处理积压的退订请求 |
+| [`Clear`](Clear.md) | 清空所有订阅 |
+| [`Invoke`](Invoke.md) | 调用所有订阅的回调 |
+| [`begin`](begin.md) | 获取开始迭代器 |
+| [`end`](end.md) | 获取结束迭代器 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Core/Event.h>
+
+using namespace XCEngine::Core;
+
+// 定义事件（无参数）
+Event<> frameStartEvent;
+
+// 定义事件（带参数）
+Event<int, float> damageEvent;
+
+// 订阅
+uint64_t id = damageEvent.Subscribe([](int damage, float time) {
+    printf("Damage: %d at time %f\n", damage, time);
+});
+
+// 触发事件
+damageEvent.Invoke(100, 3.14f);
+
+// 退订
+damageEvent.Unsubscribe(id);
+
+// 清空
+frameStartEvent.Clear();
+```
+
+## 相关文档
+
+- [Core 模块总览](../core.md) - 返回模块总览
--- a/docs/api/core/filewriter/Close.md
+++ b/docs/api/core/filewriter/Close.md
@@ -0,0 +1,40 @@
+# FileWriter::Close
+
+```cpp
+void Close();
+```
+
+关闭文件。
+
+**描述**
+
+关闭当前打开的文件。如果文件未打开，则什么都不做。析构函数会自动调用此方法。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/FileWriter.h>
+
+using namespace XCEngine::Core;
+
+FileWriter writer;
+
+if (writer.Open("data.txt")) {
+    writer.Write("Some data\n");
+    writer.Flush();
+    writer.Close();
+}
+
+// 文件已关闭，可再次打开其他文件
+if (writer.Open("other.txt")) {
+    writer.Write("New content\n");
+}
+// 析构时自动关闭
+```
+
+## 相关文档
+
+- [FileWriter 总览](filewriter.md) - 返回类总览
+- [Open](Open.md) - 打开文件
--- a/docs/api/core/filewriter/Flush.md
+++ b/docs/api/core/filewriter/Flush.md
@@ -0,0 +1,45 @@
+# FileWriter::Flush
+
+```cpp
+bool Flush();
+```
+
+刷新缓冲区。
+
+**描述**
+
+将缓冲区中的数据强制写入磁盘，确保数据持久化。在写入大量数据后应调用此方法以确保数据已保存。
+
+**返回：** `bool` - 是否刷新成功
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/FileWriter.h>
+#include <string>
+
+using namespace XCEngine::Core;
+
+FileWriter writer("output.txt");
+if (writer.IsOpen()) {
+    // 写入大量数据
+    for (int i = 0; i < 1000; i++) {
+        writer.Write("Line ");
+        writer.Write(std::to_string(i).c_str());
+        writer.Write("\n");
+    }
+    
+    // 刷新确保数据写入磁盘
+    writer.Flush();
+    
+    // 数据已安全保存
+    writer.Close();
+}
+```
+
+## 相关文档
+
+- [FileWriter 总览](filewriter.md) - 返回类总览
+- [Write](Write.md) - 写入数据
--- a/docs/api/core/filewriter/IsOpen.md
+++ b/docs/api/core/filewriter/IsOpen.md
@@ -0,0 +1,43 @@
+# FileWriter::IsOpen
+
+```cpp
+bool IsOpen() const;
+```
+
+检查文件是否已打开。
+
+**描述**
+
+返回文件是否已成功打开并可用于写入。
+
+**返回：** `bool` - 文件是否已打开
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/FileWriter.h>
+
+using namespace XCEngine::Core;
+
+FileWriter writer1;
+if (writer1.IsOpen()) {
+    // 不会执行
+    writer1.Write("test");
+}
+
+// 打开文件
+FileWriter writer2("output.txt");
+if (writer2.IsOpen()) {
+    printf("File opened successfully\n");
+    writer2.Write("Content");
+} else {
+    printf("Failed to open file\n");
+}
+```
+
+## 相关文档
+
+- [FileWriter 总览](filewriter.md) - 返回类总览
+- [Open](Open.md) - 打开文件
--- a/docs/api/core/filewriter/Open.md
+++ b/docs/api/core/filewriter/Open.md
@@ -0,0 +1,53 @@
+# FileWriter::Open
+
+```cpp
+bool Open(const char* filePath, bool append = false);
+```
+
+打开文件。
+
+**描述**
+
+打开指定路径的文件，准备写入。如果之前已打开文件，会先关闭。返回是否成功打开文件。
+
+**参数：**
+- `filePath` - 要打开的文件路径
+- `append` - 是否以追加模式打开，默认为覆盖模式
+
+**返回：** `bool` - 是否成功打开
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/FileWriter.h>
+
+using namespace XCEngine::Core;
+
+FileWriter writer;
+
+// 打开文件（覆盖模式）
+if (writer.Open("output.txt")) {
+    writer.Write("Hello\n");
+    writer.Close();
+}
+
+// 打开文件（追加模式）
+if (writer.Open("log.txt", true)) {
+    writer.Write("Another line\n");
+    writer.Flush();
+}
+
+// 检查是否成功
+FileWriter writer2;
+if (!writer2.Open("/invalid/path/file.txt")) {
+    printf("Failed to open file\n");
+}
+```
+
+## 相关文档
+
+- [FileWriter 总览](filewriter.md) - 返回类总览
+- [Close](Close.md) - 关闭文件
+- [IsOpen](IsOpen.md) - 检查文件状态
--- a/docs/api/core/filewriter/Write.md
+++ b/docs/api/core/filewriter/Write.md
@@ -0,0 +1,48 @@
+# FileWriter::Write
+
+```cpp
+bool Write(const char* data, size_t length);
+bool Write(const Containers::String& str);
+```
+
+写入数据到文件。
+
+**描述**
+
+将数据写入文件。如果文件未打开，操作会失败。
+
+**参数：**
+- `data` - 要写入的字符数据
+- `length` - 要写入的字节数
+- `str` - 要写入的 String 对象
+
+**返回：** `bool` - 是否写入成功
+
+**复杂度：** O(n) 其中 n 为写入的字节数
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/FileWriter.h>
+#include <XCEngine/Containers/String.h>
+
+using namespace XCEngine::Core;
+
+FileWriter writer("output.txt");
+if (writer.IsOpen()) {
+    // 写入原始字符数组
+    writer.Write("Hello, World!", 13);
+    writer.Write("\n", 1);
+    
+    // 写入 String
+    Containers::String message = "This is a test string";
+    writer.Write(message);
+    
+    writer.Flush();
+}
+```
+
+## 相关文档
+
+- [FileWriter 总览](filewriter.md) - 返回类总览
+- [Flush](Flush.md) - 刷新缓冲区
--- a/docs/api/core/filewriter/filewriter.md
+++ b/docs/api/core/filewriter/filewriter.md
@@ -0,0 +1,66 @@
+# FileWriter
+
+**命名空间**: `XCEngine::Core`
+
+**类型**: `class`
+
+**描述**: 文件写入工具类，提供简单的文件写入操作封装。
+
+## 概述
+
+`FileWriter` 是一个轻量级的文件写入工具，封装了 `FILE*` 接口，提供便捷的字符串和二进制数据写入功能。它支持追加模式和自动资源管理（RAII）。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `FileWriter()` | 默认构造（不打开文件） |
+| `FileWriter(const char* filePath, bool append = false)` | 构造并打开文件 |
+| `~FileWriter()` | 析构函数，自动关闭文件 |
+| [`Open`](Open.md) | 打开文件，append=true 时为追加模式 |
+| [`Close`](Close.md) | 关闭文件 |
+| [`IsOpen`](IsOpen.md) | 检查文件是否已打开 |
+| [`Write`](Write.md) | 写入数据 |
+| [`Flush`](Flush.md) | 刷新缓冲区 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Core/FileWriter.h>
+#include <XCEngine/Containers/String.h>
+
+using namespace XCEngine::Core;
+
+// 方式1：构造时打开
+FileWriter writer("output.txt", false);
+if (writer.IsOpen()) {
+    writer.Write("Hello, World!\n");
+    writer.Write("Line 2\n");
+    writer.Flush();
+}
+
+// 方式2：先构造再打开
+FileWriter writer2;
+if (writer2.Open("log.txt")) {
+    writer2.Write("Application started\n");
+    writer2.Close();
+}
+
+// 追加模式
+FileWriter appendWriter("log.txt", true);
+if (appendWriter.IsOpen()) {
+    appendWriter.Write("Another log entry\n");
+    appendWriter.Flush();
+}
+
+// 使用 String 写入
+Containers::String content = "Content written from String";
+FileWriter writer3("data.txt");
+writer3.Write(content);
+```
+
+## 相关文档
+
+- [Core 模块总览](../core.md) - 返回模块总览
+- [Logger](../../debug/logger/logger.md) - 日志系统
+- [FileLogSink](../../debug/filelogsink/filelogsink.md) - 文件日志输出
--- a/docs/api/core/refcounted/AddRef.md
+++ b/docs/api/core/refcounted/AddRef.md
@@ -0,0 +1,40 @@
+# RefCounted::AddRef
+
+```cpp
+void AddRef();
+```
+
+增加引用计数。
+
+**描述**
+
+原子地增加引用计数。在复制 `RefCounted` 指针或传递引用时调用此方法。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/RefCounted.h>
+
+class MyObject : public RefCounted {
+public:
+    void DoSomething() { /* ... */ }
+};
+
+// 创建对象（构造时 refCount = 1）
+MyObject* obj = new MyObject();
+
+// 手动增加引用
+obj->AddRef();  // refCount = 2
+obj->AddRef();  // refCount = 3
+
+// 需要释放额外的引用
+obj->Release();  // refCount = 2
+obj->Release();  // refCount = 1
+```
+
+## 相关文档
+
+- [RefCounted 总览](refcounted.md) - 返回类总览
+- [Release](Release.md) - 减少引用计数
--- a/docs/api/core/refcounted/GetRefCount.md
+++ b/docs/api/core/refcounted/GetRefCount.md
@@ -0,0 +1,43 @@
+# RefCounted::GetRefCount
+
+```cpp
+uint32_t GetRefCount() const;
+```
+
+获取当前引用计数。
+
+**描述**
+
+返回当前的引用计数值。由于使用 `std::atomic` 实现，因此是线程安全的。
+
+**返回：** `uint32_t` - 当前引用计数
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/RefCounted.h>
+
+class MyObject : public RefCounted {
+public:
+    void Debug() {
+        printf("RefCount: %u\n", GetRefCount());
+    }
+};
+
+MyObject* obj = new MyObject();
+printf("After create: %u\n", obj->GetRefCount());  // 1
+
+obj->AddRef();
+printf("After AddRef: %u\n", obj->GetRefCount());  // 2
+
+obj->Release();
+printf("After Release: %u\n", obj->GetRefCount()); // 1
+```
+
+## 相关文档
+
+- [RefCounted 总览](refcounted.md) - 返回类总览
+- [AddRef](AddRef.md) - 增加引用计数
+- [Release](Release.md) - 减少引用计数
--- a/docs/api/core/refcounted/Release.md
+++ b/docs/api/core/refcounted/Release.md
@@ -0,0 +1,39 @@
+# RefCounted::Release
+
+```cpp
+void Release();
+```
+
+减少引用计数。
+
+**描述**
+
+原子地减少引用计数。当引用计数归零时，对象会自动 `delete this`。这是实现自动内存管理的关键方法。
+
+**复杂度：** O(1)（归零时为 O(n)，n 为对象大小）
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/RefCounted.h>
+
+class MyObject : public RefCounted {
+public:
+    void DoSomething() { /* ... */ }
+};
+
+// 创建对象（构造时 refCount = 1）
+MyObject* obj = new MyObject();
+
+// 手动增加引用
+obj->AddRef();  // refCount = 2
+
+// 释放引用
+obj->Release();  // refCount = 1
+obj->Release();  // refCount = 0, 对象被自动 delete
+```
+
+## 相关文档
+
+- [RefCounted 总览](refcounted.md) - 返回类总览
+- [AddRef](AddRef.md) - 增加引用计数
--- a/docs/api/core/refcounted/refcounted.md
+++ b/docs/api/core/refcounted/refcounted.md
@@ -0,0 +1,44 @@
+# RefCounted
+
+**命名空间**: `XCEngine::Core`
+
+**类型**: `class`
+
+**描述**: 引用计数基类，提供线程安全的引用计数生命周期管理。
+
+## 概述
+
+`RefCounted` 是一个简单的引用计数基类。当引用计数归零时，对象会自动删除。它提供了 `AddRef` 和 `Release` 方法，线程安全地管理引用计数。
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| `RefCounted()` | 构造函数，初始引用计数为 1 |
+| `virtual ~RefCounted()` | 虚析构函数 |
+| [`AddRef`](AddRef.md) | 增加引用计数 |
+| [`Release`](Release.md) | 减少引用计数（归零时自动 delete this） |
+| [`GetRefCount`](GetRefCount.md) | 获取当前引用计数 |
+
+## 使用示例
+
+```cpp
+class MyObject : public RefCounted {
+public:
+    MyObject() { /* ... */ }
+    ~MyObject() { /* ... */ }
+    
+    void DoSomething() { /* ... */ }
+};
+
+// 使用
+MyObject* obj = new MyObject();  // refCount = 1
+obj->AddRef();                   // refCount = 2
+obj->Release();                   // refCount = 1
+obj->Release();                   // refCount = 0, 自动 delete
+```
+
+## 相关文档
+
+- [Core 模块总览](../core.md) - 返回模块总览
+- [SmartPtr](../smartptr/smartptr.md) - 智能指针
--- a/docs/api/core/smartptr/MakeRef.md
+++ b/docs/api/core/smartptr/MakeRef.md
@@ -0,0 +1,51 @@
+# SmartPtr::MakeRef
+
+```cpp
+template<typename T, typename... Args>
+Ref<T> MakeRef(Args&&... args);
+```
+
+创建共享指针的工厂函数。
+
+**描述**
+
+`MakeRef` 是创建 `Ref<T>` 的工厂函数，使用完美转发将参数传递给 `T` 的构造函数。相比直接使用 `std::make_shared`，代码更简洁。
+
+**模板参数：**
+- `T` - 被创建对象的类型
+- `Args` - 构造函数的参数类型
+
+**参数：**
+- `args` - 转发给 T 构造函数的参数
+
+**返回：** `Ref<T>` - 新创建的共享指针
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/SmartPtr.h>
+
+class MyClass {
+public:
+    MyClass(int a, int b) : m_a(a), m_b(b) {}
+    int GetSum() const { return m_a + m_b; }
+private:
+    int m_a, m_b;
+};
+
+// 创建共享指针
+Core::Ref<MyClass> ref = Core::MakeRef<MyClass>(10, 20);
+printf("Sum: %d\n", ref->GetSum());
+
+// 使用 lambda
+Core::Ref<std::function<void()>> callback = Core::MakeRef<std::function<void()>>([]() {
+    printf("Callback invoked!\n");
+});
+```
+
+## 相关文档
+
+- [SmartPtr 总览](smartptr.md) - 返回类总览
+- [Ref](Ref.md) - Ref 类型说明
--- a/docs/api/core/smartptr/MakeUnique.md
+++ b/docs/api/core/smartptr/MakeUnique.md
@@ -0,0 +1,49 @@
+# SmartPtr::MakeUnique
+
+```cpp
+template<typename T, typename... Args>
+UniqueRef<T> MakeUnique(Args&&... args);
+```
+
+创建独占指针的工厂函数。
+
+**描述**
+
+`MakeUnique` 是创建 `UniqueRef<T>` 的工厂函数，使用完美转发将参数传递给 `T` 的构造函数。相比直接使用 `std::make_unique`，代码更简洁。
+
+**模板参数：**
+- `T` - 被创建对象的类型
+- `Args` - 构造函数的参数类型
+
+**参数：**
+- `args` - 转发给 T 构造函数的参数
+
+**返回：** `UniqueRef<T>` - 新创建的独占指针
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/SmartPtr.h>
+
+class MyClass {
+public:
+    MyClass(int value) : m_value(value) {}
+    int GetValue() const { return m_value; }
+private:
+    int m_value;
+};
+
+// 创建独占指针
+Core::UniqueRef<MyClass> unique = Core::MakeUnique<MyClass>(42);
+printf("Value: %d\n", unique->GetValue());
+
+// 转移所有权
+Core::UniqueRef<MyClass> moved = Core::MakeUnique<MyClass>(100);
+```
+
+## 相关文档
+
+- [SmartPtr 总览](smartptr.md) - 返回类总览
+- [UniqueRef](UniqueRef.md) - UniqueRef 类型说明
--- a/docs/api/core/smartptr/Ref.md
+++ b/docs/api/core/smartptr/Ref.md
@@ -0,0 +1,40 @@
+# SmartPtr::Ref
+
+```cpp
+template<typename T>
+using Ref = std::shared_ptr<T>;
+```
+
+共享引用智能指针类型别名。
+
+**描述**
+
+`Ref<T>` 是 `std::shared_ptr<T>` 的类型别名，提供共享所有权的智能指针。多个 `Ref` 可以指向同一个对象，通过引用计数管理生命周期。当最后一个 `Ref` 被销毁时，对象会被自动删除。
+
+**模板参数：**
+- `T` - 被托管对象的类型
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/SmartPtr.h>
+
+class MyClass {
+public:
+    void DoSomething() { /* ... */ }
+};
+
+Core::Ref<MyClass> ref1 = Core::MakeRef<MyClass>();
+Core::Ref<MyClass> ref2 = ref1;  // 共享所有权
+
+if (ref1) {
+    ref1->DoSomething();
+}
+```
+
+## 相关文档
+
+- [SmartPtr 总览](smartptr.md) - 返回类总览
+- [MakeRef](MakeRef.md) - 创建 Ref 的工厂函数
--- a/docs/api/core/smartptr/UniqueRef.md
+++ b/docs/api/core/smartptr/UniqueRef.md
@@ -0,0 +1,46 @@
+# SmartPtr::UniqueRef
+
+```cpp
+template<typename T>
+using UniqueRef = std::unique_ptr<T>;
+```
+
+独占所有权的智能指针类型别名。
+
+**描述**
+
+`UniqueRef<T>` 是 `std::unique_ptr<T>` 的类型别名，提供独占所有权的智能指针。每个对象只能有一个 `UniqueRef` 持有，当 `UniqueRef` 被销毁时，对象会被自动删除。不能复制，只能移动。
+
+**模板参数：**
+- `T` - 被托管对象的类型
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/SmartPtr.h>
+
+class MyClass {
+public:
+    void DoSomething() { /* ... */ }
+};
+
+Core::UniqueRef<MyClass> unique = Core::MakeUnique<MyClass>();
+
+if (unique) {
+    unique->DoSomething();
+}
+
+// 自定义删除器
+Core::UniqueRef<FILE, decltype(&fclose)> 
+    file(fopen("test.txt", "r"), &fclose);
+
+// 转移所有权
+Core::UniqueRef<MyClass> moved = std::move(unique);
+```
+
+## 相关文档
+
+- [SmartPtr 总览](smartptr.md) - 返回类总览
+- [MakeUnique](MakeUnique.md) - 创建 UniqueRef 的工厂函数
--- a/docs/api/core/smartptr/smartptr.md
+++ b/docs/api/core/smartptr/smartptr.md
@@ -0,0 +1,64 @@
+# SmartPtr
+
+**命名空间**: `XCEngine::Core`
+
+**类型**: `header-only`
+
+**描述**: 智能指针类型别名和工厂函数，提供 `std::shared_ptr` 和 `std::unique_ptr` 的简化接口。
+
+## 概述
+
+`Core::SmartPtr` 提供了 `std::shared_ptr` 和 `std::unique_ptr` 的类型别名和工厂函数，使智能指针的使用更加简洁。
+
+## 类型别名
+
+| 别名 | 底层类型 | 描述 |
+|------|----------|------|
+| `Core::Ref<T>` | `std::shared_ptr<T>` | 共享引用智能指针 |
+| `Core::UniqueRef<T>` | `std::unique_ptr<T>` | 独占所有权的智能指针 |
+
+## 工厂函数
+
+| 函数 | 返回值 | 描述 |
+|------|--------|------|
+| `Core::MakeRef<T>(Args&&... args)` | `Ref<T>` | 创建共享指针 |
+| `Core::MakeUnique<T>(Args&&... args)` | `UniqueRef<T>` | 创建独占指针 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [`Ref`](Ref.md) | `std::shared_ptr<T>` 类型别名 |
+| [`UniqueRef`](UniqueRef.md) | `std::unique_ptr<T>` 类型别名 |
+| [`MakeRef`](MakeRef.md) | 创建共享指针的工厂函数 |
+| [`MakeUnique`](MakeUnique.md) | 创建独占指针的工厂函数 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Core/Core.h>
+
+// 使用 Ref（共享指针）
+Core::Ref<MyClass> ref = Core::MakeRef<MyClass>(arg1, arg2);
+
+// 使用 UniqueRef（独占指针）
+Core::UniqueRef<MyClass> unique = Core::MakeUnique<MyClass>();
+
+// 传递所有权
+Core::Ref<MyClass> ref2 = ref;  // 引用计数 +1
+
+// 检查有效性
+if (ref) {
+    ref->DoSomething();
+}
+
+// 自定义删除器
+Core::UniqueRef<FILE, decltype(&fclose)> 
+    file(fopen("test.txt", "r"), &fclose);
+```
+
+## 相关文档
+
+- [Core 模块总览](../core.md) - 返回模块总览
+- [RefCounted](../refcounted/refcounted.md) - 引用计数基类
+- [Types](../types/types.md) - 类型别名
--- a/docs/api/core/types/byte.md
+++ b/docs/api/core/types/byte.md
@@ -0,0 +1,30 @@
+# Types::byte
+
+```cpp
+using byte = uint8_t;
+```
+
+字节类型别名，对应 `uint8_t` 类型。
+
+**描述**
+
+`byte` 是 1 字节无符号整数类型，专门用于表示原始字节数据。语义上比 `uint8` 更清晰，适用于二进制数据、内存缓冲区等场景。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::byte header[4] = {0x00, 0x01, 0x02, 0x03};
+Core::byte flags = 0b11001010;
+
+// 内存缓冲区
+Core::byte* buffer = new Core::byte[1024];
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [uint8](uint8.md) - 底层类型
--- a/docs/api/core/types/int16.md
+++ b/docs/api/core/types/int16.md
@@ -0,0 +1,27 @@
+# Types::int16
+
+```cpp
+using int16 = int16_t;
+```
+
+16位有符号整数类型别名，对应 C++ 标准库的 `int16_t` 类型。
+
+**描述**
+
+`int16` 是 16 位（2 字节）有符号整数类型，范围为 -32,768 到 32,767。该类型别名确保跨平台一致性。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::int16 shortValue = -10000;
+Core::int16 maxValue = 32767;
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [uint16](uint16.md) - 对应的无符号类型
--- a/docs/api/core/types/int32.md
+++ b/docs/api/core/types/int32.md
@@ -0,0 +1,30 @@
+# Types::int32
+
+```cpp
+using int32 = int32_t;
+```
+
+32位有符号整数类型别名，对应 C++ 标准库的 `int32_t` 类型。
+
+**描述**
+
+`int32` 是 32 位（4 字节）有符号整数类型，范围为 -2,147,483,648 到 2,147,483,647。该类型别名确保跨平台一致性，是最常用的整数类型。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::int32 score = 1000000;
+Core::int32 negative = -500000;
+
+// 函数参数类型
+void SetHealth(Core::int32 health);
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [uint32](uint32.md) - 对应的无符号类型
--- a/docs/api/core/types/int64.md
+++ b/docs/api/core/types/int64.md
@@ -0,0 +1,30 @@
+# Types::int64
+
+```cpp
+using int64 = int64_t;
+```
+
+64位有符号整数类型别名，对应 C++ 标准库的 `int64_t` 类型。
+
+**描述**
+
+`int64` 是 64 位（8 字节）有符号整数类型，范围为 -9,223,372,036,854,775,808 到 9,223,372,036,854,775,807。该类型别名用于需要大范围整数的场景，如时间戳、大文件大小等。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::int64 largeNumber = 9223372036854775807LL;
+Core::int64 fileSize = 1099511627776LL;  // 1TB
+
+// 时间戳（毫秒）
+Core::int64 timestamp = 1700000000000LL;
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [uint64](uint64.md) - 对应的无符号类型
--- a/docs/api/core/types/int8.md
+++ b/docs/api/core/types/int8.md
@@ -0,0 +1,28 @@
+# Types::int8
+
+```cpp
+using int8 = int8_t;
+```
+
+8位有符号整数类型别名，对应 C++ 标准库的 `int8_t` 类型。
+
+**描述**
+
+`int8` 是 8 位（1 字节）有符号整数类型，范围为 -128 到 127。该类型别名确保跨平台一致性。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::int8 signedByte = -50;
+Core::int8 maxValue = 127;
+Core::int8 minValue = -128;
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [uint8](uint8.md) - 对应的无符号类型
--- a/docs/api/core/types/types.md
+++ b/docs/api/core/types/types.md
@@ -0,0 +1,63 @@
+# Types
+
+**命名空间**: `XCEngine::Core`
+
+**类型**: `header` (type aliases)
+
+**头文件**: `XCEngine/Core/Types.h`
+
+**描述**: 基础类型别名定义，提供跨平台一致的基础类型名称。
+
+## 概述
+
+`Types.h` 定义了一组类型别名，简化了标准库类型的使用，并提供跨平台一致性。
+
+## 类型别名
+
+| 别名 | 实际类型 | 描述 |
+|------|----------|------|
+| `int8` | `int8_t` | 8位有符号整数 |
+| `int16` | `int16_t` | 16位有符号整数 |
+| `int32` | `int32_t` | 32位有符号整数 |
+| `int64` | `int64_t` | 64位有符号整数 |
+| `uint8` | `uint8_t` | 8位无符号整数 |
+| `uint16` | `uint16_t` | 16位无符号整数 |
+| `uint32` | `uint32_t` | 32位无符号整数 |
+| `uint64` | `uint64_t` | 64位无符号整数 |
+| `byte` | `uint8_t` | 字节类型 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [`int8`](int8.md) | 8位有符号整数类型别名 |
+| [`int16`](int16.md) | 16位有符号整数类型别名 |
+| [`int32`](int32.md) | 32位有符号整数类型别名 |
+| [`int64`](int64.md) | 64位有符号整数类型别名 |
+| [`uint8`](uint8.md) | 8位无符号整数类型别名 |
+| [`uint16`](uint16.md) | 16位无符号整数类型别名 |
+| [`uint32`](uint32.md) | 32位无符号整数类型别名 |
+| [`uint64`](uint64.md) | 64位无符号整数类型别名 |
+| [`byte`](byte.md) | 字节类型别名 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+// 使用类型别名
+Core::int32 count = 100;
+Core::uint64 id = 1234567890;
+Core::byte flags = 0xFF;
+
+// 数组定义
+Core::uint8 buffer[1024];
+
+// 函数参数
+void ProcessData(Core::uint32 size, const Core::int8* data);
+```
+
+## 相关文档
+
+- [Core 模块总览](../core.md) - 返回模块总览
+- [SmartPtr](../smartptr/smartptr.md) - 智能指针
--- a/docs/api/core/types/uint16.md
+++ b/docs/api/core/types/uint16.md
@@ -0,0 +1,30 @@
+# Types::uint16
+
+```cpp
+using uint16 = uint16_t;
+```
+
+16位无符号整数类型别名，对应 C++ 标准库的 `uint16_t` 类型。
+
+**描述**
+
+`uint16` 是 16 位（2 字节）无符号整数类型，范围为 0 到 65,535。常用于 Unicode 字符、端口号等场景。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::uint16 port = 8080;
+Core::uint16 maxConnections = 65535;
+
+// Unicode 字符
+Core::uint16 unicodeChar = 0x4E2D;
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [int16](int16.md) - 对应的有符号类型
--- a/docs/api/core/types/uint32.md
+++ b/docs/api/core/types/uint32.md
@@ -0,0 +1,30 @@
+# Types::uint32
+
+```cpp
+using uint32 = uint32_t;
+```
+
+32位无符号整数类型别名，对应 C++ 标准库的 `uint32_t` 类型。
+
+**描述**
+
+`uint32` 是 32 位（4 字节）无符号整数类型，范围为 0 到 4,294,967,295。常用于 ID、计数、大小等场景。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::uint32 entityId = 1000000;
+Core::uint32 maxItems = 4294967295U;
+
+// 数组大小
+Core::uint32 arraySize = 1000;
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [int32](int32.md) - 对应的有符号类型
--- a/docs/api/core/types/uint64.md
+++ b/docs/api/core/types/uint64.md
@@ -0,0 +1,30 @@
+# Types::uint64
+
+```cpp
+using uint64 = uint64_t;
+```
+
+64位无符号整数类型别名，对应 C++ 标准库的 `uint64_t` 类型。
+
+**描述**
+
+`uint64` 是 64 位（8 字节）无符号整数类型，范围为 0 到 18,446,744,073,709,551,615。用于需要极大整数范围的场景，如大文件大小、精确时间等。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::uint64 largeFileSize = 1099511627776ULL;  // 1TB
+Core::uint64 maxValue = 18446744073709551615ULL;
+
+// 高精度时间戳（微秒）
+Core::uint64 microseconds = 1700000000000000ULL;
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [int64](int64.md) - 对应的有符号类型
--- a/docs/api/core/types/uint8.md
+++ b/docs/api/core/types/uint8.md
@@ -0,0 +1,30 @@
+# Types::uint8
+
+```cpp
+using uint8 = uint8_t;
+```
+
+8位无符号整数类型别名，对应 C++ 标准库的 `uint8_t` 类型。
+
+**描述**
+
+`uint8` 是 8 位（1 字节）无符号整数类型，范围为 0 到 255。常用于字节数据、颜色分量（RGB）等场景。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+#include <XCEngine/Core/Types.h>
+
+Core::uint8 flags = 0xFF;
+Core::uint8 red = 255;
+
+// 字节数组
+Core::uint8 buffer[256];
+```
+
+## 相关文档
+
+- [Types 总览](types.md) - 返回类型总览
+- [int8](int8.md) - 对应的有符号类型