docs: rebuild audio and core api docs

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

@@ -6,53 +6,111 @@
 
 **头文件**: `XCEngine/Core/Containers/String.h`
 
-**描述**: 定义 `XCEngine/Core/Containers` 子目录中的 `String` public API。
+**描述**: 引擎自定义可变字符串类型，提供基本值语义、拼接和常见文本处理能力。
 
-## 概述
+## 角色概述
 
-`String.h` 是 `XCEngine/Core/Containers` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`String` 是当前引擎代码里最常见的基础文本容器之一。它承担的职责比较明确：
 
-## 声明概览
+- 保存 UTF-8 风格的字节字符串内容
+- 对外暴露 C 风格字符串接口 `CStr()`
+- 提供最常用的拼接、查找、截取和大小写转换功能
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `String` | `class` | 头文件中的公开声明。 |
+它更接近一个轻量版 `std::string`，而不是功能完全对齐的完整替代品。
 
-## 公共方法
+## 生命周期与所有权
 
-| 方法 | 描述 |
-|------|------|
-| [String()](Constructor.md) | 构造对象。 |
-| [~String()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [operator=](OperatorAssign.md) | 公开方法，详见头文件声明。 |
-| [operator+=](OperatorPlusAssign.md) | 公开方法，详见头文件声明。 |
-| [Substring](Substring.md) | 公开方法，详见头文件声明。 |
-| [Trim](Trim.md) | 公开方法，详见头文件声明。 |
-| [ToLower](ToLower.md) | 公开方法，详见头文件声明。 |
-| [ToUpper](ToUpper.md) | 公开方法，详见头文件声明。 |
-| [Find](Find.md) | 查找并返回匹配对象。 |
-| [StartsWith](StartsWith.md) | 公开方法，详见头文件声明。 |
-| [EndsWith](EndsWith.md) | 公开方法，详见头文件声明。 |
-| [CStr](CStr.md) | 公开方法，详见头文件声明。 |
-| [Length](Length.md) | 公开方法，详见头文件声明。 |
-| [Capacity](Capacity.md) | 公开方法，详见头文件声明。 |
-| [Empty](Empty.md) | 公开方法，详见头文件声明。 |
-| [operator[]](OperatorSubscript.md) | 公开方法，详见头文件声明。 |
-| [Clear](Clear.md) | 清空内部数据。 |
-| [Reserve](Reserve.md) | 公开方法，详见头文件声明。 |
-| [Resize](Resize.md) | 公开方法，详见头文件声明。 |
+- 默认构造会分配一个长度为 1 的缓冲区，并写入 `'\0'`
+- 从 `const char*` 构造时会复制输入内容
+- 拷贝构造和拷贝赋值执行深拷贝
+- 移动构造和移动赋值直接转移内部缓冲区指针
+- 析构时用 `delete[]` 释放内部字符缓冲
+
+当前实现里最需要注意的点是移动后的对象状态：
+
+- move 之后，源对象的 `m_data` 会被置为 `nullptr`
+- 这意味着“被移动后的 `String` 仍像空字符串一样安全可读”并不是当前实现保证
+
+析构和再次赋值仍然安全，但不要假设对 moved-from 对象调用 `CStr()` 一定还能得到 `""`。
+
+## 当前行为
+
+### 拼接与修改
+
+- `operator+=(String)` 和 `operator+=(const char*)` 会在容量不足时重新分配到“刚好够用”的新缓冲
+- `operator+=(char)` 的扩容策略则是 `newLength * 2`
+- `Clear()` 只把长度归零并写入终止符，不释放容量
+- `Reserve()` 只增不减
+- `Resize()` 会补齐字符并保持尾部 `'\0'`
+
+### 文本处理
+
+- `Substring(pos, len)` 越界起点会返回空字符串
+- `Trim()` 只裁剪空格、`\t`、`\n`、`\r`
+- `ToLower()` / `ToUpper()` 只处理 ASCII 英文字母
+- `StartsWith()` / `EndsWith()` 支持 `String` 和 `const char*` 两种形式
+
+### 查找
+
+`Find(const char* str, SizeType pos)` 当前有一个和 `std::string` 不同的语义：
+
+- 当 `str` 为空字符串时，它返回 `npos`
+
+也就是说，当前实现并没有采用“空模式匹配当前位置”的标准库习惯。
 
 ## std::hash 特化
 
-```cpp
-namespace std {
-    template<> struct hash<XCEngine::Containers::String>;
-}
-```
+`String.h` 当前提供了 `std::hash<XCEngine::Containers::String>` 特化，因此 [HashMap](../HashMap/HashMap.md) 可以直接把 `String` 作为 key 使用。哈希算法当前是经典的 djb2 风格实现。
 
-`String.h` 同时提供 `std::hash<XCEngine::Containers::String>` 特化，可直接用于哈希容器键类型。
+## 设计取向
+
+商业引擎经常保留自己的字符串类型，不只是为了“重复造轮子”，而是为了：
+
+- 统一公共 API 形状
+- 未来接 allocator、profile、serialization hook
+- 避免在所有模块边界直接暴露标准库类型
+
+`String` 当前已经承担了这种基础角色，但仍然偏简单实现，没有做复杂的小字符串优化或完整字符集语义处理。
+
+## 线程语义
+
+- 类本身没有锁。
+- 所有修改操作都直接写内部缓冲。
+- 默认应按普通单对象值类型理解，不提供并发安全保证。
+
+## 当前实现限制
+
+- 没有 small string optimization。
+- 大小写转换只覆盖 ASCII。
+- `Find("")` 返回 `npos`，不同于 `std::string`。
+- moved-from 对象不保证仍然表现为空字符串。
+- 没有自定义 allocator 接入路径。
+
+## 相关方法
+
+- [Constructor](Constructor.md)
+- [Destructor](Destructor.md)
+- [OperatorAssign](OperatorAssign.md)
+- [OperatorPlusAssign](OperatorPlusAssign.md)
+- [Substring](Substring.md)
+- [Trim](Trim.md)
+- [ToLower](ToLower.md)
+- [ToUpper](ToUpper.md)
+- [Find](Find.md)
+- [StartsWith](StartsWith.md)
+- [EndsWith](EndsWith.md)
+- [CStr](CStr.md)
+- [Length](Length.md)
+- [Capacity](Capacity.md)
+- [Empty](Empty.md)
+- [OperatorSubscript](OperatorSubscript.md)
+- [Clear](Clear.md)
+- [Reserve](Reserve.md)
+- [Resize](Resize.md)
 
 ## 相关文档
 
-- [当前目录](../Containers.md) - 返回 `Containers` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [当前模块](../Containers.md)
+- [Array](../Array/Array.md)
+- [HashMap](../HashMap/HashMap.md)
+- [API 总索引](../../../../main.md)