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/containers/hashmap/clear.md
+++ b/docs/api/containers/hashmap/clear.md
@@ -0,0 +1,34 @@
+# HashMap::Clear
+
+```cpp
+void Clear();
+```
+
+清空哈希表中的所有元素，将元素数量置为 0。桶的数量保持不变。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(m_bucketCount)，需要清空所有桶
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+map.Insert(1, "one");
+map.Insert(2, "two");
+map.Insert(3, "three");
+
+std::cout << "Size before clear: " << map.Size() << std::endl; // 输出 3
+
+map.Clear();
+
+std::cout << "Size after clear: " << map.Size() << std::endl; // 输出 0
+std::cout << "Empty: " << (map.Empty() ? "yes" : "no") << std::endl; // 输出 "yes"
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Erase](erase.md) - 删除单个元素
--- a/docs/api/containers/hashmap/constructor.md
+++ b/docs/api/containers/hashmap/constructor.md
@@ -0,0 +1,31 @@
+# HashMap::HashMap
+
+```cpp
+HashMap();
+explicit HashMap(size_t bucketCount, Memory::IAllocator* allocator = nullptr);
+```
+
+构造哈希表实例。
+
+**参数：**
+- `bucketCount` - 初始桶的数量，默认为 16。若传入 0，则自动调整为 16。
+- `allocator` - 内存分配器指针，默认为 `nullptr`（使用默认分配器）。
+
+**返回：** 无
+
+**复杂度：** O(bucketCount)，需要初始化所有桶
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map1;
+
+XCEngine::Containers::HashMap<int, const char*> map2(32);
+
+auto customAllocator = XCEngine::Memory::GetDefaultAllocator();
+XCEngine::Containers::HashMap<int, const char*> map3(64, customAllocator);
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
--- a/docs/api/containers/hashmap/contains.md
+++ b/docs/api/containers/hashmap/contains.md
@@ -0,0 +1,35 @@
+# HashMap::Contains
+
+```cpp
+bool Contains(const Key& key) const;
+```
+
+检查哈希表中是否包含指定的键。
+
+**参数：**
+- `key` - 要检查的键
+
+**返回：** 如果键存在返回 `true`，否则返回 `false`。
+
+**复杂度：** O(1) 平均，最坏 O(n)
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+map.Insert(1, "one");
+map.Insert(2, "two");
+
+if (map.Contains(1)) {
+    std::cout << "Key 1 exists" << std::endl; // 输出 "Key 1 exists"
+}
+
+if (!map.Contains(99)) {
+    std::cout << "Key 99 does not exist" << std::endl; // 输出 "Key 99 does not exist"
+}
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Find](find.md) - 查找键对应的值
--- a/docs/api/containers/hashmap/copy-move.md
+++ b/docs/api/containers/hashmap/copy-move.md
@@ -0,0 +1,34 @@
+# HashMap::Copy/Move 构造
+
+```cpp
+HashMap(const HashMap& other);
+HashMap(HashMap&& other) noexcept;
+```
+
+拷贝构造和移动构造。
+
+**参数：**
+- `other` - 源哈希表（拷贝版本为 `const` 引用，移动版本为右值引用）
+
+**返回：** 无（构造函数）
+
+**复杂度：**
+- 拷贝构造：O(m_bucketCount + other.m_size)
+- 移动构造：O(m_bucketCount)，移动构造需要遍历所有桶以重新建立桶的指针关系
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, std::string> map1;
+map1.Insert(1, "hello");
+map1.Insert(2, "world");
+
+XCEngine::Containers::HashMap<int, std::string> map2(map1); // 拷贝构造
+
+XCEngine::Containers::HashMap<int, std::string> map3(std::move(map1)); // 移动构造，map1 在此调用后状态不确定
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [operator=](operator-assign.md) - 赋值运算符
--- a/docs/api/containers/hashmap/destructor.md
+++ b/docs/api/containers/hashmap/destructor.md
@@ -0,0 +1,27 @@
+# HashMap::~HashMap
+
+```cpp
+~HashMap();
+```
+
+析构函数，清空所有元素并释放资源。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(n)，需要清空所有桶中的元素
+
+**示例：**
+
+```cpp
+{
+    XCEngine::Containers::HashMap<int, std::string> map;
+    map.Insert(1, "hello");
+    map.Insert(2, "world");
+} // map 在此自动析构，所有资源被正确释放
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
--- a/docs/api/containers/hashmap/erase.md
+++ b/docs/api/containers/hashmap/erase.md
@@ -0,0 +1,37 @@
+# HashMap::Erase
+
+```cpp
+bool Erase(const Key& key);
+```
+
+删除指定键对应的元素。
+
+**参数：**
+- `key` - 要删除的键
+
+**返回：** 如果元素被删除返回 `true`，如果键不存在返回 `false`。
+
+**复杂度：** O(1) 平均，最坏 O(n)
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+map.Insert(1, "one");
+map.Insert(2, "two");
+map.Insert(3, "three");
+
+bool erased = map.Erase(2); // 返回 true
+
+if (!map.Contains(2)) {
+    std::cout << "Key 2 removed" << std::endl; // 输出 "Key 2 removed"
+}
+
+bool notErased = map.Erase(99); // 返回 false，键不存在
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Insert](insert.md) - 插入键值对
+- [Clear](clear.md) - 清空所有元素
--- a/docs/api/containers/hashmap/find.md
+++ b/docs/api/containers/hashmap/find.md
@@ -0,0 +1,39 @@
+# HashMap::Find
+
+```cpp
+Value* Find(const Key& key);
+const Value* Find(const Key& key) const;
+```
+
+根据键查找对应的值指针。
+
+**参数：**
+- `key` - 要查找的键
+
+**返回：** 如果找到，返回指向值的指针；否则返回 `nullptr`。
+
+**复杂度：** O(1) 平均，最坏 O(n)（同一桶中有多个键发生哈希冲突）
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+map.Insert(1, "one");
+map.Insert(2, "two");
+
+const char* value1 = map.Find(1);
+if (value1) {
+    std::cout << "Found: " << value1 << std::endl; // 输出 "Found: one"
+}
+
+const char* value2 = map.Find(99);
+if (!value2) {
+    std::cout << "Not found" << std::endl; // 输出 "Not found"
+}
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Contains](contains.md) - 检查是否包含键
+- [operator[]](./operator-subscript.md) - 下标访问
--- a/docs/api/containers/hashmap/hashmap.md
+++ b/docs/api/containers/hashmap/hashmap.md
@@ -0,0 +1,80 @@
+# HashMap
+
+**命名空间**: `XCEngine::Containers`
+
+**类型**: `class` (template)
+
+**描述**: 模板哈希表容器，提供键值对存储和快速查找。
+
+## 概述
+
+`HashMap<Key, Value>` 是一个模板哈希表容器，使用动态数组作为桶来解决哈希冲突，支持键值对的插入、查找和删除操作。
+
+## 公共类型
+
+### Pair
+
+| 成员 | 类型 | 描述 |
+|------|------|------|
+| `first` | `Key` | 键 |
+| `second` | `Value` | 值 |
+
+### 迭代器
+
+| 别名 | 类型 | 描述 |
+|------|------|------|
+| `Iterator` | `typename Array<Pair>::Iterator` | 迭代器类型 |
+| `ConstIterator` | `typename Array<Pair>::ConstIterator` | 常量迭代器类型 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [Constructor](constructor.md) | 构造哈希表实例 |
+| [Destructor](destructor.md) | 析构函数 |
+| [operator=](operator-assign.md) | 赋值运算符 |
+| [Copy/Move](copy-move.md) | 拷贝/移动构造 |
+| [operator[]](operator-subscript.md) | 下标访问（不存在时插入） |
+| [Find](find.md) | 查找键对应的值指针 |
+| [Contains](contains.md) | 检查是否包含键 |
+| [Insert](insert.md) | 插入键值对 |
+| [Erase](erase.md) | 删除键对应的元素 |
+| [Clear](clear.md) | 清空所有元素 |
+| [Size/Empty](size.md) | 获取元素数量 |
+| [begin/end](iterator.md) | 获取迭代器 |
+| [SetAllocator](setallocator.md) | 设置内存分配器 |
+
+## 使用示例
+
+```cpp
+#include <XCEngine/Containers/HashMap.h>
+#include <iostream>
+
+int main() {
+    XCEngine::Containers::HashMap<int, const char*> map;
+
+    map.Insert(1, "one");
+    map.Insert(2, "two");
+    map.Insert(3, "three");
+
+    if (const char* value = map.Find(1)) {
+        std::cout << "Key 1: " << value << std::endl;
+    }
+
+    std::cout << "Size: " << map.Size() << std::endl;
+
+    for (auto it = map.begin(); it != map.end(); ++it) {
+        std::cout << it->first << " -> " << it->second << std::endl;
+    }
+
+    map.Erase(2);
+    std::cout << "Contains 2: " << (map.Contains(2) ? "yes" : "no") << std::endl;
+
+    return 0;
+}
+```
+
+## 相关文档
+
+- [Array](../array/array.md) - 动态数组
+- [Memory 模块](../../memory/memory.md) - 内存分配器
--- a/docs/api/containers/hashmap/insert.md
+++ b/docs/api/containers/hashmap/insert.md
@@ -0,0 +1,38 @@
+# HashMap::Insert
+
+```cpp
+bool Insert(const Key& key, const Value& value);
+bool Insert(const Key& key, Value&& value);
+bool Insert(Pair&& pair);
+```
+
+插入键值对。如果键已存在，则更新其值并返回 `false`；否则插入新元素并返回 `true`。
+
+**参数：**
+- `key` - 要插入的键
+- `value` - 要插入的值（const 版本为拷贝，&& 版本为移动）
+- `pair` - 包含键值对的 `Pair` 结构（右值）
+
+**返回：** 如果插入成功（键不存在）返回 `true`，如果键已存在（更新值）返回 `false`。
+
+**复杂度：** O(1) 平均，最坏 O(n)（包括可能的 rehash）
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, std::string> map;
+
+bool inserted1 = map.Insert(1, "one");   // 返回 true
+bool inserted2 = map.Insert(1, "ONE");   // 返回 false，更新现有值
+
+bool inserted3 = map.Insert(2, std::string("two")); // 移动语义版本
+
+XCEngine::Containers::HashMap<int, std::string>::Pair p{3, "three"};
+bool inserted4 = map.Insert(std::move(p)); // Pair 移动版本
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [operator[]](./operator-subscript.md) - 下标访问（总是插入）
+- [Erase](erase.md) - 删除键对应的元素
--- a/docs/api/containers/hashmap/iterator.md
+++ b/docs/api/containers/hashmap/iterator.md
@@ -0,0 +1,34 @@
+# HashMap::begin / end
+
+```cpp
+Iterator begin();
+Iterator end();
+ConstIterator begin() const;
+ConstIterator end() const;
+```
+
+获取哈希表的迭代器。迭代器遍历所有桶中的元素。
+
+**参数：** 无
+
+**返回：** 返回指向第一个元素和末尾（最后一个元素之后）位置的迭代器。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+map.Insert(1, "one");
+map.Insert(2, "two");
+map.Insert(3, "three");
+
+for (auto it = map.begin(); it != map.end(); ++it) {
+    std::cout << it->first << " -> " << it->second << std::endl;
+}
+// 输出顺序不确定，取决于哈希桶的内部布局
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
--- a/docs/api/containers/hashmap/operator-assign.md
+++ b/docs/api/containers/hashmap/operator-assign.md
@@ -0,0 +1,36 @@
+# HashMap::operator=
+
+```cpp
+HashMap& operator=(const HashMap& other);
+HashMap& operator=(HashMap&& other) noexcept;
+```
+
+赋值运算符，用另一个 HashMap 的内容替换当前内容。
+
+**参数：**
+- `other` - 源哈希表（拷贝版本为 `const` 引用，移动版本为右值引用）
+
+**返回：** 对当前对象的引用 (`*this`)
+
+**复杂度：**
+- 拷贝赋值：O(m_bucketCount + other.m_size)
+- 移动赋值：O(m_size)，需要先清空当前内容
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map1;
+map1.Insert(1, "one");
+map1.Insert(2, "two");
+
+XCEngine::Containers::HashMap<int, const char*> map2;
+map2 = map1; // 拷贝赋值
+
+XCEngine::Containers::HashMap<int, const char*> map3;
+map3 = std::move(map1); // 移动赋值，map1 在此调用后状态不确定
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Copy/Move](copy-move.md) - 拷贝/移动构造
--- a/docs/api/containers/hashmap/operator-subscript.md
+++ b/docs/api/containers/hashmap/operator-subscript.md
@@ -0,0 +1,33 @@
+# HashMap::operator[]
+
+```cpp
+Value& operator[](const Key& key);
+```
+
+按下标访问键对应的值。如果键不存在，则插入一个默认构造的值并返回引用。
+
+**参数：**
+- `key` - 要访问的键
+
+**返回：** 对应值的引用。如果键不存在，则返回一个默认构造的 `Value` 的引用。
+
+**复杂度：** O(1) 平均，最坏 O(n)（发生 rehash 时）
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, std::string> map;
+
+map[1] = "one";          // 插入键 1，值 "one"
+map[2] = "two";          // 插入键 2，值 "two"
+
+std::string& value = map[1]; // 获取键 1 对应的值，结果为 "one"
+
+map[3];                  // 插入键 3，值为 std::string 的默认构造值
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Find](find.md) - 查找键对应的值（不插入）
+- [Insert](insert.md) - 插入键值对（不覆盖已存在的键）
--- a/docs/api/containers/hashmap/setallocator.md
+++ b/docs/api/containers/hashmap/setallocator.md
@@ -0,0 +1,28 @@
+# HashMap::SetAllocator
+
+```cpp
+void SetAllocator(Memory::IAllocator* allocator);
+```
+
+设置哈希表的内存分配器。
+
+**参数：**
+- `allocator` - 内存分配器指针，可以为 `nullptr`（使用默认分配器）
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+
+// 设置自定义分配器（如果使用内存分配器接口）
+// map.SetAllocator(customAllocator);
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览
+- [Memory 模块](../../memory/memory.md) - 内存分配器
--- a/docs/api/containers/hashmap/size.md
+++ b/docs/api/containers/hashmap/size.md
@@ -0,0 +1,35 @@
+# HashMap::Size / Empty
+
+```cpp
+size_t Size() const;
+bool Empty() const;
+```
+
+获取哈希表的元素数量或判断是否为空。
+
+**参数：** 无
+
+**返回：**
+- `Size()` - 返回元素数量
+- `Empty()` - 容器为空返回 `true`，否则返回 `false`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+XCEngine::Containers::HashMap<int, const char*> map;
+
+std::cout << "Empty: " << (map.Empty() ? "yes" : "no") << std::endl; // 输出 "yes"
+std::cout << "Size: " << map.Size() << std::endl; // 输出 0
+
+map.Insert(1, "one");
+map.Insert(2, "two");
+
+std::cout << "Empty: " << (map.Empty() ? "yes" : "no") << std::endl; // 输出 "no"
+std::cout << "Size: " << map.Size() << std::endl; // 输出 2
+```
+
+## 相关文档
+
+- [HashMap 总览](hashmap.md) - 返回类总览