docs: rebuild audio and core api docs

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

@@ -1,22 +1,68 @@
 # Containers
 
-**命名空间**: `XCEngine::Core::Containers`
+**命名空间**: `XCEngine::Containers`
 
 **类型**: `submodule`
 
-**描述**: 字符串、数组和哈希表等核心容器。
+**头文件**: `XCEngine/Core/Containers/Containers.h`
+
+**描述**: 定义引擎自定义字符串、动态数组和哈希表等基础容器。
 
 ## 概览
 
-该目录与 `XCEngine/Core/Containers` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。
+`Core/Containers` 是当前引擎最底层的数据结构层之一。它提供的不是一整套 STL 替代品，而是一组在引擎内部频繁出现、接口风格统一的基础容器：
+
+- [String](String/String.md)
+- [Array](Array/Array.md)
+- [HashMap](HashMap/HashMap.md)
+
+从设计方向看，这和商业引擎里常见的“自定义基础容器层”很像。这样做的好处是：
+
+- 对外 API 风格统一
+- 可以逐步引入引擎自己的分配器和调试支持
+- 跨模块时不必把标准库类型直接暴露到所有接口里
+
+但按当前实现，它们仍然是轻量容器，而不是 fully-featured STL 等价物。
+
+## umbrella header
+
+`Containers.h` 当前只是一个聚合头文件，负责包含：
+
+- `Array.h`
+- `String.h`
+- `HashMap.h`
+
+它自身没有新增独立类型，所以这里直接把它并入模块页说明，不再保留一份重复的 `Containers/Containers.md` 类型页。
+
+## 设计要点
+
+- `Array` 和 `HashMap` 当前都是头文件模板实现。
+- `String` 采用单独 `.cpp`，用堆分配维护可变字符缓冲。
+- 三个容器都使用值语义，但当前都偏“简单直接实现”，而不是“最大化性能和异常安全”的成熟版本。
+- `Array::SetAllocator()` 和 `HashMap::SetAllocator()` 当前只是记录指针，没有真正接管底层分配。
+
+## 当前实现现状
+
+- `String` 已覆盖最常用的拼接、子串、前后缀和大小写转换能力。
+- `Array` 已可覆盖大部分顺序容器用途，但没有边界检查，也没有完整 allocator 接入。
+- `HashMap` 已可用于基本查找和插入，但迭代器语义与 `operator[]` 的扩容返回路径都还存在当前实现问题。
 
 ## 头文件
 
 - [Array](Array/Array.md) - `Array.h`
-- [Containers](Containers/Containers.md) - `Containers.h`
 - [HashMap](HashMap/HashMap.md) - `HashMap.h`
 - [String](String/String.md) - `String.h`
 
+## 推荐阅读顺序
+
+1. 先读 [String](String/String.md)，理解当前项目里最常见的自定义字符串约定。
+2. 再读 [Array](Array/Array.md)，这是其他模块最常用的顺序容器。
+3. 最后读 [HashMap](HashMap/HashMap.md)，注意它当前的迭代和扩容边界。
+
+## 相关指南
+
+- [Custom Containers, Value Semantics, And Interop](../../../_guides/Core/Containers/Custom-Containers-Value-Semantics-And-Interop.md)
+
 ## 相关文档
 
 - [上级目录](../Core.md)