docs: rebuild audio and core api docs

docs/api/XCEngine/Core/Containers/HashMap/HashMap.md

@@ -2,42 +2,106 @@
 
 **命名空间**: `XCEngine::Containers`
 
-**类型**: `class`
+**类型**: `class template`
 
 **头文件**: `XCEngine/Core/Containers/HashMap.h`
 
-**描述**: 定义 `XCEngine/Core/Containers` 子目录中的 `HashMap` public API。
+**描述**: 基于桶数组和线性桶内查找实现的轻量哈希表。
 
-## 概述
+## 角色概述
 
-`HashMap.h` 是 `XCEngine/Core/Containers` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`HashMap<Key, Value>` 是当前容器层提供的关联容器实现。它的基本结构是：
 
-## 声明概览
+- 外层一个 `Array<Bucket>`
+- 每个 bucket 内部再保存一个 `Array<Pair>`
+- 通过 `std::hash<Key>` 选择 bucket
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `HashMap` | `class` | 头文件中的公开声明。 |
+这种实现方式简单直接，适合项目早期快速提供可用的键值查找能力，也便于与自定义 `String` 和 `Array` 生态打通。
 
-## 公共方法
+## 当前行为
 
-| 方法 | 描述 |
-|------|------|
-| [HashMap()](Constructor.md) | 构造对象。 |
-| [~HashMap()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [operator=](OperatorAssign.md) | 公开方法，详见头文件声明。 |
-| [operator[]](OperatorSubscript.md) | 公开方法，详见头文件声明。 |
-| [Find](Find.md) | 查找并返回匹配对象。 |
-| [Contains](Contains.md) | 公开方法，详见头文件声明。 |
-| [Insert](Insert.md) | 公开方法，详见头文件声明。 |
-| [Erase](Erase.md) | 公开方法，详见头文件声明。 |
-| [Clear](Clear.md) | 清空内部数据。 |
-| [Size](Size.md) | 公开方法，详见头文件声明。 |
-| [Empty](Empty.md) | 公开方法，详见头文件声明。 |
-| [begin](begin.md) | 公开方法，详见头文件声明。 |
-| [end](end.md) | 公开方法，详见头文件声明。 |
-| [SetAllocator](SetAllocator.md) | 设置相关状态或配置。 |
+### 插入与查找
+
+- 默认 bucket 数量是 `16`
+- `Insert(key, value)` 如果 key 已存在，会覆盖旧值并返回 `false`
+- `Find(key)` 返回值指针，不存在时返回 `nullptr`
+- `Contains(key)` 基于同一套 bucket 查找逻辑
+- `operator[]` 在 key 不存在时会插入一个默认构造的 `Value`
+
+### 扩容
+
+当前负载因子阈值是 `0.75f`。超过后会调用 `Resize()`，并把所有 pair 重新散列到新的 bucket 数组中。
+
+### 擦除
+
+`Erase(key)` 当前会：
+
+- 在 bucket 内线性查找
+- 若找到目标，则用 bucket 内最后一个元素覆盖当前位置
+- 再 `PopBack()`
+
+这意味着同一 bucket 内 pair 的相对顺序不稳定。
+
+## 设计取向
+
+商业引擎常会提供自定义哈希表，不只是为了控制接口风格，也为了未来对内存分配、调试、序列化和平台兼容做统一约束。`HashMap` 当前已经承担了这类基础职责，尤其适合：
+
+- 少量到中等规模的引擎内查找表
+- 与 `Containers::String` 组合使用
+
+但它离成熟标准容器还有一段距离。
+
+## 迭代器语义
+
+当前最重要、也最容易被误用的点，是 `begin()` / `end()`：
+
+- `begin()` 返回的是第一个 bucket 的 `pairs.begin()`
+- `end()` 返回的是最后一个 bucket 的 `pairs.end()`
+
+这并不能形成“跨所有 bucket 的完整连续迭代区间”。也就是说，当前 `HashMap` 的 `begin()` / `end()` 不是可靠的整表遍历接口。
+
+如果按标准容器心智模型去做范围 for 或手写全表迭代，行为并不成立。
+
+## 一个当前实现风险
+
+`operator[]` 在插入新 key 后，如果触发了 `Resize()`，当前实现会在扩容之后继续返回扩容前 bucket 引用上的元素引用。按源码来看，这里存在返回悬空引用的风险。
+
+因此，当前版本里不应把“缺失 key 时通过 `operator[]` 插入并立即持有返回引用”当成绝对安全路径，尤其是在表接近扩容阈值时。
+
+## 线程语义
+
+- 没有内部锁。
+- 所有读写都直接操作 bucket 数组。
+- 默认按非线程安全容器使用。
+
+## 当前实现限制
+
+- bucket 内查找是线性的。
+- `begin()` / `end()` 当前不是可靠的整表迭代器语义。
+- `operator[]` 在触发扩容时存在返回悬空引用风险。
+- `SetAllocator()` 当前只是保存指针，底层分配仍依赖容器默认实现。
+- 没有 `const operator[]`、没有 iterator erase、没有稳定遍历顺序。
+
+## 相关方法
+
+- [Constructor](Constructor.md)
+- [Destructor](Destructor.md)
+- [OperatorAssign](OperatorAssign.md)
+- [OperatorSubscript](OperatorSubscript.md)
+- [Find](Find.md)
+- [Contains](Contains.md)
+- [Insert](Insert.md)
+- [Erase](Erase.md)
+- [Clear](Clear.md)
+- [Size](Size.md)
+- [Empty](Empty.md)
+- [begin](begin.md)
+- [end](end.md)
+- [SetAllocator](SetAllocator.md)
 
 ## 相关文档
 
-- [当前目录](../Containers.md) - 返回 `Containers` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [当前模块](../Containers.md)
+- [String](../String/String.md)
+- [Array](../Array/Array.md)
+- [API 总索引](../../../../main.md)