docs: rebuild Memory API content

docs/api/XCEngine/Memory/Allocator/Allocate.md

@@ -1,32 +1,30 @@
 # IAllocator::Allocate
 
-公开方法，详见头文件声明。
+申请一块内存。
 
 ```cpp
 virtual void* Allocate(size_t size, size_t alignment = 0) = 0;
 ```
 
-该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+这是纯虚接口。不同实现对 `size`、`alignment` 和失败条件的支持程度不同：
-- `size` - 参数语义详见头文件声明。
-- `alignment` - 参数语义详见头文件声明。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+- `LinearAllocator` 支持顺序分配，但对齐语义目前有限。
+- `PoolAllocator` 只在 `size <= blockSize` 且还有空闲块时成功。
+- `ProxyAllocator` 只是转发到底层分配器。
 
-**示例：**
+## 参数
 
-```cpp
+- `size` - 请求大小。
-#include <XCEngine/Memory/Allocator.h>
+- `alignment` - 对齐要求；`0` 表示实现自定默认行为。
 
-void Example() {
+## 返回值
-    XCEngine::Memory::IAllocator object;
+
-    // 根据上下文补齐参数后调用 IAllocator::Allocate(...)。
+- `void*` - 成功时返回可用内存；失败时通常返回 `nullptr`。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Allocator.md)
+- [返回类型总览](Allocator.md)
-- [返回模块目录](../Memory.md)
+- [Free](Free.md)
+- [Reallocate](Reallocate.md)

docs/api/XCEngine/Memory/Allocator/Allocator.md

@@ -1,38 +1,58 @@
-# Allocator
+# IAllocator
 
 **命名空间**: `XCEngine::Memory`
 
-**类型**: `class (abstract)`
+**类型**: `class (abstract interface)`
 
 **头文件**: `XCEngine/Memory/Allocator.h`
 
-**描述**: 定义 `XCEngine/Memory` 子目录中的 `Allocator` public API。
+**描述**: 定义统一的分配、释放、重分配和统计查询接口。
 
 ## 概述
 
-`Allocator.h` 是 `XCEngine/Memory` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`IAllocator` 是当前内存模块的基础抽象。它把“如何申请和回收一块内存”统一成一组稳定接口，让上层代码不必直接依赖具体分配器实现。
 
-## 声明概览
+它的职责分成两部分：
 
-| 声明 | 类型 | 说明 |
+- 内存操作：`Allocate`、`Free`、`Reallocate`
-|------|------|------|
+- 统计查询：`GetTotalAllocated`、`GetTotalFreed`、`GetPeakAllocated`、`GetAllocationCount`
-| `IAllocator` | `class` | 头文件中的公开声明。 |
 
-## 公共方法
+## 设计目的
 
-| 方法 | 描述 |
+这类接口在引擎里很有价值，因为：
+
+- 容器、资源系统和工具系统可以接受任意分配器实现。
+- 不同策略可以共存，例如线性分配器、对象池、系统分配器代理。
+- 调试和统计逻辑可以围绕接口做组合，而不是侵入所有调用点。
+
+## 当前实现约束
+
+- `IAllocator` 只定义形状，不保证线程安全。
+- 统计方法的语义由具体实现决定；当前不同分配器的统计精度并不一致。
+- 不是每个实现都完整支持 `Free` 和 `Reallocate`。
+
+## 已知实现
+
+- [LinearAllocator](../LinearAllocator/LinearAllocator.md)
+- [PoolAllocator](../PoolAllocator/PoolAllocator.md)
+- [ProxyAllocator](../ProxyAllocator/ProxyAllocator.md)
+- `SystemAllocator`：当前仅存在于 `engine/src/Memory/Memory.cpp` 内部，不是公共类型。
+
+## 公开方法
+
+| 方法 | 说明 |
 |------|------|
-| [~IAllocator()](Destructor.md) | 销毁对象并释放相关资源。 |
+| [Destructor](Destructor.md) | 虚析构函数。 |
-| [Allocate](Allocate.md) | 公开方法，详见头文件声明。 |
+| [Allocate](Allocate.md) | 申请内存。 |
-| [Free](Free.md) | 公开方法，详见头文件声明。 |
+| [Free](Free.md) | 释放内存。 |
-| [Reallocate](Reallocate.md) | 公开方法，详见头文件声明。 |
+| [Reallocate](Reallocate.md) | 调整已分配内存大小。 |
-| [GetTotalAllocated](GetTotalAllocated.md) | 获取相关状态或对象。 |
+| [GetTotalAllocated](GetTotalAllocated.md) | 查询累计已分配量。 |
-| [GetTotalFreed](GetTotalFreed.md) | 获取相关状态或对象。 |
+| [GetTotalFreed](GetTotalFreed.md) | 查询累计已释放量。 |
-| [GetPeakAllocated](GetPeakAllocated.md) | 获取相关状态或对象。 |
+| [GetPeakAllocated](GetPeakAllocated.md) | 查询峰值分配量。 |
-| [GetAllocationCount](GetAllocationCount.md) | 获取相关状态或对象。 |
+| [GetAllocationCount](GetAllocationCount.md) | 查询当前或累计分配次数。 |
-| [GetName](GetName.md) | 获取相关状态或对象。 |
+| [GetName](GetName.md) | 查询分配器名称。 |
 
 ## 相关文档
 
-- [当前目录](../Memory.md) - 返回 `Memory` 平行目录
+- [当前模块](../Memory.md)
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [Allocator Selection And Current Limits](../../../_guides/Memory/Allocator-Selection-And-Current-Limits.md)

docs/api/XCEngine/Memory/Allocator/Destructor.md

@@ -1,29 +1,15 @@
-# IAllocator::~IAllocator()
+# IAllocator::Destructor
 
-销毁对象并释放相关资源。
+通过基类指针安全销毁分配器。
 
 ```cpp
 virtual ~IAllocator() = default;
 ```
 
-该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+虚析构函数保证 `std::unique_ptr<IAllocator>` 或基类指针可以正确销毁派生分配器对象。
-
-**返回：** `void` - 无返回值。
-
-**示例：**
-
-```cpp
-#include <XCEngine/Memory/Allocator.h>
-
-void Example() {
-    XCEngine::Memory::IAllocator object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Allocator.md)
+- [返回类型总览](Allocator.md)
-- [返回模块目录](../Memory.md)

docs/api/XCEngine/Memory/Allocator/Free.md

@@ -1,31 +1,28 @@
 # IAllocator::Free
 
-公开方法，详见头文件声明。
+释放一块已分配内存。
 
 ```cpp
 virtual void Free(void* ptr) = 0;
 ```
 
-该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+这是纯虚接口，但并不是每个实现都真正支持独立释放：
-- `ptr` - 参数语义详见头文件声明。
 
-**返回：** `void` - 无返回值。
+- `LinearAllocator` 当前为空实现。
+- `PoolAllocator` 支持把 block 放回空闲链表。
+- `ProxyAllocator` 会把调用转发到底层分配器。
 
-**示例：**
+## 参数
 
-```cpp
+- `ptr` - 待释放指针。
-#include <XCEngine/Memory/Allocator.h>
 
-void Example() {
+## 返回值
-    XCEngine::Memory::IAllocator object;
+
-    // 根据上下文补齐参数后调用 IAllocator::Free(...)。
+- 无。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Allocator.md)
+- [返回类型总览](Allocator.md)
-- [返回模块目录](../Memory.md)
+- [Allocate](Allocate.md)

docs/api/XCEngine/Memory/Allocator/GetAllocationCount.md

@@ -1,30 +1,23 @@
 # IAllocator::GetAllocationCount
 
-获取相关状态或对象。
+查询分配计数。
 
 ```cpp
 virtual size_t GetAllocationCount() const = 0;
 ```
 
-该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+这是纯虚统计接口，但不同实现的口径不同：
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+- `PoolAllocator` 当前返回已分配 block 数。
+- `ProxyAllocator` 当前返回内部统计中的 allocationCount。
+- `LinearAllocator` 当前始终返回 `0`。
 
-**示例：**
+## 返回值
 
-```cpp
+- `size_t` - 实现定义的分配计数。
-#include <XCEngine/Memory/Allocator.h>
-
-void Example() {
-    XCEngine::Memory::IAllocator object;
-    // 根据上下文补齐参数后调用 IAllocator::GetAllocationCount(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Allocator.md)
+- [返回类型总览](Allocator.md)
-- [返回模块目录](../Memory.md)

docs/api/XCEngine/Memory/Allocator/GetName.md

@@ -1,30 +1,19 @@
 # IAllocator::GetName
 
-获取相关状态或对象。
+查询分配器名称。
 
 ```cpp
 virtual const char* GetName() const = 0;
 ```
 
-该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+返回一个只读 C 字符串，用于调试、日志或报表标识。不同实现可能返回固定字面量，也可能返回构造时提供的名称。
 
-**返回：** `const char*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `const char*` - 分配器名称。
-
-```cpp
-#include <XCEngine/Memory/Allocator.h>
-
-void Example() {
-    XCEngine::Memory::IAllocator object;
-    // 根据上下文补齐参数后调用 IAllocator::GetName(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Allocator.md)
+- [返回类型总览](Allocator.md)
-- [返回模块目录](../Memory.md)

docs/api/XCEngine/Memory/Allocator/GetPeakAllocated.md

@@ -1,30 +1,22 @@
 # IAllocator::GetPeakAllocated
 
-获取相关状态或对象。
+查询峰值分配量。
 
 ```cpp
 virtual size_t GetPeakAllocated() const = 0;
 ```
 
-该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+这是纯虚统计接口，但当前实现并不统一：
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+- `ProxyAllocator` 维护的是净分配峰值。
+- `PoolAllocator` 和 `LinearAllocator` 当前返回的是固定容量上界，而不是真实历史峰值。
 
-**示例：**
+## 返回值
 
-```cpp
+- `size_t` - 实现定义的峰值分配量。
-#include <XCEngine/Memory/Allocator.h>
-
-void Example() {
-    XCEngine::Memory::IAllocator object;
-    // 根据上下文补齐参数后调用 IAllocator::GetPeakAllocated(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Allocator.md)
+- [返回类型总览](Allocator.md)
-- [返回模块目录](../Memory.md)

docs/api/XCEngine/Memory/Allocator/GetTotalAllocated.md

@@ -1,30 +1,23 @@
 # IAllocator::GetTotalAllocated
 
-获取相关状态或对象。
+查询累计或当前已分配量。
 
 ```cpp
 virtual size_t GetTotalAllocated() const = 0;
 ```
 
-该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+这是纯虚统计接口。当前不同实现的语义不同：
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+- `LinearAllocator` 返回当前已用大小。
+- `PoolAllocator` 返回当前已占用 block 总字节数。
+- `ProxyAllocator` 返回累计请求分配字节数。
 
-**示例：**
+## 返回值
 
-```cpp
+- `size_t` - 实现定义的分配量。
-#include <XCEngine/Memory/Allocator.h>
-
-void Example() {
-    XCEngine::Memory::IAllocator object;
-    // 根据上下文补齐参数后调用 IAllocator::GetTotalAllocated(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Allocator.md)
+- [返回类型总览](Allocator.md)
-- [返回模块目录](../Memory.md)

docs/api/XCEngine/Memory/Allocator/GetTotalFreed.md

@@ -1,30 +1,19 @@
 # IAllocator::GetTotalFreed
 
-获取相关状态或对象。
+查询累计或当前已释放量。
 
 ```cpp
 virtual size_t GetTotalFreed() const = 0;
 ```
 
-该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+这是纯虚统计接口。当前各实现语义并不一致，而且 `ProxyAllocator` 的释放统计目前不准确。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `size_t` - 实现定义的释放量。
-
-```cpp
-#include <XCEngine/Memory/Allocator.h>
-
-void Example() {
-    XCEngine::Memory::IAllocator object;
-    // 根据上下文补齐参数后调用 IAllocator::GetTotalFreed(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Allocator.md)
+- [返回类型总览](Allocator.md)
-- [返回模块目录](../Memory.md)

docs/api/XCEngine/Memory/Allocator/Reallocate.md

@@ -1,32 +1,29 @@
 # IAllocator::Reallocate
 
-公开方法，详见头文件声明。
+调整一块已分配内存的大小。
 
 ```cpp
 virtual void* Reallocate(void* ptr, size_t newSize) = 0;
 ```
 
-该方法声明于 `XCEngine/Memory/Allocator.h`，当前页面用于固定 `IAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+这是纯虚接口，但当前并不是每个实现都支持：
-- `ptr` - 参数语义详见头文件声明。
-- `newSize` - 参数语义详见头文件声明。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+- `LinearAllocator` 当前返回 `nullptr`
+- `PoolAllocator` 当前返回 `nullptr`
+- `ProxyAllocator` 只是转发到底层分配器
 
-**示例：**
+## 参数
 
-```cpp
+- `ptr` - 原始指针。
-#include <XCEngine/Memory/Allocator.h>
+- `newSize` - 新大小。
 
-void Example() {
+## 返回值
-    XCEngine::Memory::IAllocator object;
+
-    // 根据上下文补齐参数后调用 IAllocator::Reallocate(...)。
+- `void*` - 成功时返回新指针；当前某些实现始终返回 `nullptr`。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](Allocator.md)
+- [返回类型总览](Allocator.md)
-- [返回模块目录](../Memory.md)
+- [Allocate](Allocate.md)

docs/api/XCEngine/Memory/LinearAllocator/Allocate.md

@@ -1,32 +1,37 @@
 # LinearAllocator::Allocate
 
-公开方法，详见头文件声明。
+从当前偏移量开始分配一块线性内存。
 
 ```cpp
 void* Allocate(size_t size, size_t alignment = 8) override;
 ```
 
-该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现流程：
-- `size` - 参数语义详见头文件声明。
-- `alignment` - 参数语义详见头文件声明。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+1. `size == 0` 时直接返回 `nullptr`
+2. 以 `m_buffer + m_offset` 作为当前地址
+3. 如果 `alignment > 0`，按当前地址计算 misalignment，并把 padding 直接加到消耗的 `size` 上
+4. 如果 `m_offset + size > m_capacity`，返回 `nullptr`
+5. 返回当前偏移位置指针，并推进 `m_offset`
 
-**示例：**
+需要特别注意：
 
-```cpp
+- 当前实现增加的是“消耗大小”，不是“返回地址偏移”，因此它不保证返回指针一定满足任意给定对齐要求。
-#include <XCEngine/Memory/LinearAllocator.h>
+- 分配是单调推进的，不支持单个块释放。
 
-void Example() {
+## 参数
-    XCEngine::Memory::LinearAllocator object;
+
-    // 根据上下文补齐参数后调用 LinearAllocator::Allocate(...)。
+- `size` - 请求大小。
-    (void)object;
+- `alignment` - 期望对齐；当前默认值为 `8`。
-}
+
-```
+## 返回值
+
+- `void*` - 成功时返回缓冲区中的一段内存；容量不足时返回 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](LinearAllocator.md)
+- [返回类型总览](LinearAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Clear](Clear.md)
+- [GetUsedSize](GetUsedSize.md)

docs/api/XCEngine/Memory/LinearAllocator/Clear.md

@@ -1,30 +1,22 @@
 # LinearAllocator::Clear
 
-清空内部数据。
+一次性回收当前所有线性分配结果。
 
 ```cpp
 void Clear();
 ```
 
-该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现仅执行：
-
-**返回：** `void` - 无返回值。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/LinearAllocator.h>
+m_offset = 0;
-
-void Example() {
-    XCEngine::Memory::LinearAllocator object;
-    // 根据上下文补齐参数后调用 LinearAllocator::Clear(...)。
-    (void)object;
-}
 ```
 
+它不会逐块调用析构，也不会清零缓冲区内容。旧内存中的字节仍然存在，但逻辑上已经全部视为可重新分配。
+
 ## 相关文档
 
-- [返回类总览](LinearAllocator.md)
+- [返回类型总览](LinearAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetMarker](GetMarker.md)

docs/api/XCEngine/Memory/LinearAllocator/Constructor.md

@@ -1,30 +1,30 @@
-# LinearAllocator::LinearAllocator()
+# LinearAllocator::Constructor
 
-构造对象。
+构造一个固定容量的线性分配器。
 
 ```cpp
 explicit LinearAllocator(size_t size, IAllocator* parent = nullptr);
 ```
 
-该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现会保存总容量和父分配器指针，然后申请底层缓冲区：
-- `size` - 参数语义详见头文件声明。
-- `parent` - 参数语义详见头文件声明。
 
-**返回：** `void` - 无返回值。
+- 如果 `parent` 非空，通过父分配器申请 `size` 字节。
+- 如果 `parent` 为空，当前实现直接调用 `_aligned_malloc(size, 8)`。
 
-**示例：**
+这意味着“无父分配器”路径当前是明显的 Windows 风格实现。
 
-```cpp
+## 参数
-#include <XCEngine/Memory/LinearAllocator.h>
 
-void Example() {
+- `size` - 缓冲区容量。
-    XCEngine::Memory::LinearAllocator object;
+- `parent` - 可选的父分配器。
-}
+
-```
+## 返回值
+
+- 无。
 
 ## 相关文档
 
-- [返回类总览](LinearAllocator.md)
+- [返回类型总览](LinearAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Destructor](Destructor.md)

docs/api/XCEngine/Memory/LinearAllocator/Destructor.md

@@ -1,29 +1,19 @@
-# LinearAllocator::~LinearAllocator()
+# LinearAllocator::Destructor
 
-销毁对象并释放相关资源。
+销毁线性分配器并释放底层缓冲区。
 
 ```cpp
 ~LinearAllocator() override;
 ```
 
-该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现根据构造来源选择释放方式：
 
-**返回：** `void` - 无返回值。
+- 如果有父分配器，则调用 `m_parent->Free(m_buffer)`
-
+- 否则在 Windows 上调用 `_aligned_free(m_buffer)`，非 Windows 路径调用 `std::free(m_buffer)`
-**示例：**
-
-```cpp
-#include <XCEngine/Memory/LinearAllocator.h>
-
-void Example() {
-    XCEngine::Memory::LinearAllocator object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
 
 ## 相关文档
 
-- [返回类总览](LinearAllocator.md)
+- [返回类型总览](LinearAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Constructor](Constructor.md)

docs/api/XCEngine/Memory/LinearAllocator/Free.md

@@ -1,31 +1,24 @@
 # LinearAllocator::Free
 
-公开方法，详见头文件声明。
+释放一块线性分配结果。
 
 ```cpp
 void Free(void* ptr) override;
 ```
 
-该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现为空函数。也就是说，`LinearAllocator` 目前不支持单独释放任何块。
-- `ptr` - 参数语义详见头文件声明。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `ptr` - 当前不会被使用。
 
-```cpp
+## 返回值
-#include <XCEngine/Memory/LinearAllocator.h>
 
-void Example() {
+- 无。
-    XCEngine::Memory::LinearAllocator object;
-    // 根据上下文补齐参数后调用 LinearAllocator::Free(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](LinearAllocator.md)
+- [返回类型总览](LinearAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Clear](Clear.md)

docs/api/XCEngine/Memory/LinearAllocator/GetAllocationCount.md

@@ -1,30 +1,19 @@
 # LinearAllocator::GetAllocationCount
 
-获取相关状态或对象。
+查询分配次数。
 
 ```cpp
 size_t GetAllocationCount() const override;
 ```
 
-该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现固定返回 `0`。它不是实际分配次数统计。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `size_t` - 当前固定为 `0`。
-
-```cpp
-#include <XCEngine/Memory/LinearAllocator.h>
-
-void Example() {
-    XCEngine::Memory::LinearAllocator object;
-    // 根据上下文补齐参数后调用 LinearAllocator::GetAllocationCount(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](LinearAllocator.md)
+- [返回类型总览](LinearAllocator.md)
-- [返回模块目录](../Memory.md)

docs/api/XCEngine/Memory/LinearAllocator/GetCapacity.md

@@ -1,30 +1,20 @@
 # LinearAllocator::GetCapacity
 
-获取相关状态或对象。
+查询线性分配器的总容量。
 
 ```cpp
 size_t GetCapacity() const;
 ```
 
-该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+返回构造时保存的 `m_capacity`，不受当前已用偏移量影响。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `size_t` - 总容量。
-
-```cpp
-#include <XCEngine/Memory/LinearAllocator.h>
-
-void Example() {
-    XCEngine::Memory::LinearAllocator object;
-    // 根据上下文补齐参数后调用 LinearAllocator::GetCapacity(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](LinearAllocator.md)
+- [返回类型总览](LinearAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetUsedSize](GetUsedSize.md)

docs/api/XCEngine/Memory/LinearAllocator/GetMarker.md

@@ -1,30 +1,26 @@
 # LinearAllocator::GetMarker
 
-获取相关状态或对象。
+获取当前偏移标记。
 
 ```cpp
 void* GetMarker() const;
 ```
 
-该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现返回的是：
-
-**返回：** `void*` - 返回值语义详见头文件声明。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/LinearAllocator.h>
+reinterpret_cast<void*>(m_offset)
-
-void Example() {
-    XCEngine::Memory::LinearAllocator object;
-    // 根据上下文补齐参数后调用 LinearAllocator::GetMarker(...)。
-    (void)object;
-}
 ```
 
+也就是说，这不是缓冲区中的真实内存指针，而是把“当前 offset 值”包装成一个 `void*` 令牌，供 [SetMarker](SetMarker.md) 之后恢复使用。
+
+## 返回值
+
+- `void*` - 偏移量令牌。
+
 ## 相关文档
 
-- [返回类总览](LinearAllocator.md)
+- [返回类型总览](LinearAllocator.md)
-- [返回模块目录](../Memory.md)
+- [SetMarker](SetMarker.md)

docs/api/XCEngine/Memory/LinearAllocator/GetName.md

@@ -1,30 +1,19 @@
 # LinearAllocator::GetName
 
-获取相关状态或对象。
+查询分配器名称。
 
 ```cpp
 const char* GetName() const override;
 ```
 
-该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现固定返回 `"LinearAllocator"`。
 
-**返回：** `const char*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `const char*` - 固定名称字符串。
-
-```cpp
-#include <XCEngine/Memory/LinearAllocator.h>
-
-void Example() {
-    XCEngine::Memory::LinearAllocator object;
-    // 根据上下文补齐参数后调用 LinearAllocator::GetName(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](LinearAllocator.md)
+- [返回类型总览](LinearAllocator.md)
-- [返回模块目录](../Memory.md)

docs/api/XCEngine/Memory/LinearAllocator/GetPeakAllocated.md

@@ -1,30 +1,20 @@
 # LinearAllocator::GetPeakAllocated
 
-获取相关状态或对象。
+查询峰值分配量。
 
 ```cpp
 size_t GetPeakAllocated() const override;
 ```
 
-该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回 `m_capacity`。这表示“理论最大可用容量”，而不是历史峰值使用量。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `size_t` - 当前固定等于容量。
-
-```cpp
-#include <XCEngine/Memory/LinearAllocator.h>
-
-void Example() {
-    XCEngine::Memory::LinearAllocator object;
-    // 根据上下文补齐参数后调用 LinearAllocator::GetPeakAllocated(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](LinearAllocator.md)
+- [返回类型总览](LinearAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetCapacity](GetCapacity.md)

docs/api/XCEngine/Memory/LinearAllocator/GetTotalAllocated.md

@@ -1,30 +1,20 @@
 # LinearAllocator::GetTotalAllocated
 
-获取相关状态或对象。
+查询当前已用字节数。
 
 ```cpp
 size_t GetTotalAllocated() const override;
 ```
 
-该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回 `m_offset`。因此它表示的是“当前已消耗的线性缓冲大小”，不是历史累计分配量。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `size_t` - 当前已用字节数。
-
-```cpp
-#include <XCEngine/Memory/LinearAllocator.h>
-
-void Example() {
-    XCEngine::Memory::LinearAllocator object;
-    // 根据上下文补齐参数后调用 LinearAllocator::GetTotalAllocated(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](LinearAllocator.md)
+- [返回类型总览](LinearAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetUsedSize](GetUsedSize.md)

docs/api/XCEngine/Memory/LinearAllocator/GetTotalFreed.md

@@ -1,30 +1,19 @@
 # LinearAllocator::GetTotalFreed
 
-获取相关状态或对象。
+查询累计释放量。
 
 ```cpp
 size_t GetTotalFreed() const override;
 ```
 
-该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现固定返回 `0`，因为 `LinearAllocator` 目前不做单块释放统计。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `size_t` - 当前固定为 `0`。
-
-```cpp
-#include <XCEngine/Memory/LinearAllocator.h>
-
-void Example() {
-    XCEngine::Memory::LinearAllocator object;
-    // 根据上下文补齐参数后调用 LinearAllocator::GetTotalFreed(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](LinearAllocator.md)
+- [返回类型总览](LinearAllocator.md)
-- [返回模块目录](../Memory.md)

docs/api/XCEngine/Memory/LinearAllocator/GetUsedSize.md

@@ -1,30 +1,20 @@
 # LinearAllocator::GetUsedSize
 
-获取相关状态或对象。
+查询当前已用大小。
 
 ```cpp
 size_t GetUsedSize() const;
 ```
 
-该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现返回 `m_offset`。语义与 [GetTotalAllocated](GetTotalAllocated.md) 相同。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `size_t` - 当前已用大小。
-
-```cpp
-#include <XCEngine/Memory/LinearAllocator.h>
-
-void Example() {
-    XCEngine::Memory::LinearAllocator object;
-    // 根据上下文补齐参数后调用 LinearAllocator::GetUsedSize(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](LinearAllocator.md)
+- [返回类型总览](LinearAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetTotalAllocated](GetTotalAllocated.md)

docs/api/XCEngine/Memory/LinearAllocator/LinearAllocator.md

@@ -6,39 +6,58 @@
 
 **头文件**: `XCEngine/Memory/LinearAllocator.h`
 
-**描述**: 定义 `XCEngine/Memory` 子目录中的 `LinearAllocator` public API。
+**描述**: 以单调递增偏移量分配内存的线性分配器，适合临时或批量释放场景。
 
 ## 概述
 
-`LinearAllocator.h` 是 `XCEngine/Memory` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`LinearAllocator` 是典型的 bump / arena allocator：每次分配只推进一个偏移量，不跟踪单个块，也不支持逐块释放。它适合：
 
-## 声明概览
+- 帧级临时内存
+- 批量构建后整体清空的中间数据
+- 需要极低分配开销、但不要求单个对象回收的场景
 
-| 声明 | 类型 | 说明 |
+## 生命周期与所有权
-|------|------|------|
-| `LinearAllocator` | `class` | 继承自 `IAllocator` 的公开声明。 |
 
-## 公共方法
+- [Constructor](Constructor.md) 创建一块固定容量缓冲区。
+- 如果传入父分配器，底层缓冲由父分配器提供并在析构时归还给父分配器。
+- 如果没有父分配器，当前实现会直接在构造函数中申请原生内存。
+- [Clear](Clear.md) 会把偏移量重置为零，相当于一次性回收所有线性分配结果。
 
-| 方法 | 描述 |
+## 当前实现限制
+
+- [Free](Free.md) 目前是空实现，不会释放单个块。
+- [Reallocate](Reallocate.md) 目前始终返回 `nullptr`。
+- `GetMarker` / `SetMarker` 使用的是“偏移量令牌”，不是缓冲区中的真实指针。
+- `GetPeakAllocated` 当前直接返回总容量，而不是历史峰值使用量。
+- `GetAllocationCount` 当前始终返回 `0`。
+- `Allocate` 会尝试处理对齐，但当前实现通过“增加消耗大小”而不是“返回对齐后的指针”来处理 padding，因此不要过度依赖高阶自定义对齐保证。
+
+## 线程语义
+
+- 当前没有锁；应由调用方在单线程或外部同步前提下使用。
+
+## 公开方法
+
+| 方法 | 说明 |
 |------|------|
-| [LinearAllocator()](Constructor.md) | 构造对象。 |
+| [Constructor](Constructor.md) | 构造线性分配器。 |
-| [~LinearAllocator()](Destructor.md) | 销毁对象并释放相关资源。 |
+| [Destructor](Destructor.md) | 销毁分配器并释放底层缓冲。 |
-| [Allocate](Allocate.md) | 公开方法，详见头文件声明。 |
+| [Allocate](Allocate.md) | 从当前偏移量分配一块内存。 |
-| [Free](Free.md) | 公开方法，详见头文件声明。 |
+| [Free](Free.md) | 释放单个块；当前为空实现。 |
-| [Reallocate](Reallocate.md) | 公开方法，详见头文件声明。 |
+| [Reallocate](Reallocate.md) | 重分配块；当前返回 `nullptr`。 |
-| [Clear](Clear.md) | 清空内部数据。 |
+| [Clear](Clear.md) | 清空所有线性分配结果。 |
-| [GetMarker](GetMarker.md) | 获取相关状态或对象。 |
+| [GetMarker](GetMarker.md) | 获取当前偏移标记。 |
-| [SetMarker](SetMarker.md) | 设置相关状态或配置。 |
+| [SetMarker](SetMarker.md) | 回退或推进到指定偏移标记。 |
-| [GetUsedSize](GetUsedSize.md) | 获取相关状态或对象。 |
+| [GetUsedSize](GetUsedSize.md) | 查询当前已用大小。 |
-| [GetCapacity](GetCapacity.md) | 获取相关状态或对象。 |
+| [GetCapacity](GetCapacity.md) | 查询总容量。 |
-| [GetName](GetName.md) | 获取相关状态或对象。 |
+| [GetName](GetName.md) | 查询分配器名称。 |
-| [GetTotalAllocated](GetTotalAllocated.md) | 获取相关状态或对象。 |
+| [GetTotalAllocated](GetTotalAllocated.md) | 查询当前已用字节数。 |
-| [GetTotalFreed](GetTotalFreed.md) | 获取相关状态或对象。 |
+| [GetTotalFreed](GetTotalFreed.md) | 查询累计释放量；当前固定为 `0`。 |
-| [GetPeakAllocated](GetPeakAllocated.md) | 获取相关状态或对象。 |
+| [GetPeakAllocated](GetPeakAllocated.md) | 查询峰值分配量；当前返回容量。 |
-| [GetAllocationCount](GetAllocationCount.md) | 获取相关状态或对象。 |
+| [GetAllocationCount](GetAllocationCount.md) | 查询分配次数；当前固定为 `0`。 |
 
 ## 相关文档
 
-- [当前目录](../Memory.md) - 返回 `Memory` 平行目录
+- [当前模块](../Memory.md)
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [IAllocator](../Allocator/Allocator.md)
+- [Allocator Selection And Current Limits](../../../_guides/Memory/Allocator-Selection-And-Current-Limits.md)

docs/api/XCEngine/Memory/LinearAllocator/Reallocate.md

@@ -1,32 +1,25 @@
 # LinearAllocator::Reallocate
 
-公开方法，详见头文件声明。
+调整一块线性分配结果的大小。
 
 ```cpp
 void* Reallocate(void* ptr, size_t newSize) override;
 ```
 
-该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现直接返回 `nullptr`，没有任何重分配逻辑。
-- `ptr` - 参数语义详见头文件声明。
-- `newSize` - 参数语义详见头文件声明。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `ptr` - 当前不会被使用。
+- `newSize` - 当前不会被使用。
 
-```cpp
+## 返回值
-#include <XCEngine/Memory/LinearAllocator.h>
 
-void Example() {
+- `void*` - 当前固定返回 `nullptr`。
-    XCEngine::Memory::LinearAllocator object;
-    // 根据上下文补齐参数后调用 LinearAllocator::Reallocate(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](LinearAllocator.md)
+- [返回类型总览](LinearAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Allocate](Allocate.md)

docs/api/XCEngine/Memory/LinearAllocator/SetMarker.md

@@ -1,31 +1,30 @@
 # LinearAllocator::SetMarker
 
-设置相关状态或配置。
+把偏移量恢复到指定标记。
 
 ```cpp
 void SetMarker(void* marker);
 ```
 
-该方法声明于 `XCEngine/Memory/LinearAllocator.h`，当前页面用于固定 `LinearAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现会执行：
-- `marker` - 参数语义详见头文件声明。
-
-**返回：** `void` - 无返回值。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/LinearAllocator.h>
+m_offset = reinterpret_cast<size_t>(marker);
-
-void Example() {
-    XCEngine::Memory::LinearAllocator object;
-    // 根据上下文补齐参数后调用 LinearAllocator::SetMarker(...)。
-    (void)object;
-}
 ```
 
+也就是说，`marker` 不是缓冲区中的真实指针，而应当来自 [GetMarker](GetMarker.md) 返回的偏移量令牌。
+
+## 参数
+
+- `marker` - 偏移量令牌。
+
+## 返回值
+
+- 无。
+
 ## 相关文档
 
-- [返回类总览](LinearAllocator.md)
+- [返回类型总览](LinearAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetMarker](GetMarker.md)

docs/api/XCEngine/Memory/Memory.md

@@ -4,19 +4,51 @@
 
 **类型**: `module`
 
-**描述**: 分配器与内存管理。
+**描述**: 提供分配器抽象、线性分配器、固定块池分配器、统计代理分配器以及全局内存工厂入口。
 
-## 概览
+## 概述
 
-该目录与 `XCEngine/Memory` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。
+`XCEngine::Memory` 试图把“如何分配内存”从具体容器和系统模块中抽离出来。当前模块的公共 API 分成两层：
+
+- `IAllocator` 定义统一分配器接口。
+- `LinearAllocator`、`PoolAllocator` 和 `ProxyAllocator` 提供不同策略的具体实现。
+- `MemoryManager` 负责初始化内部系统分配器并创建若干常用分配器对象。
+
+这类设计在商业级引擎里很常见，因为不同场景对内存的需求完全不同：
+
+- 帧级临时数据更适合 arena / linear allocator。
+- 大量固定尺寸对象更适合 pool allocator。
+- 调试和统计更适合在已有分配器外面套一层 proxy / tracking allocator。
+
+## 当前实现成熟度
+
+当前公开接口比实现完整度更大，需要把这点写清楚：
+
+- `LinearAllocator` 的 `Free` 和 `Reallocate` 目前都是空实现或占位返回。
+- `PoolAllocator` 的 `Reallocate` 目前返回 `nullptr`。
+- `ProxyAllocator` 能转发分配，但其释放统计和重分配统计并不完整。
+- `MemoryManager::DumpMemoryLeaks` 和 `GenerateMemoryReport` 目前只输出标题文本。
+- `MemoryManager::SetTrackAllocations` 当前只修改标志位，没有驱动其它行为。
+- 通过 `MemoryManager` 创建且依赖系统分配器的对象，当前仍需要调用方自己保证在 `Shutdown()` 前完成销毁。
+
+## 设计要点
+
+- 引擎级分配器 API 的价值，不在于替代系统 `malloc`，而在于为不同生命周期和数据形态提供更明确的分配策略。
+- `IAllocator` 让容器和上层系统可以依赖抽象，而不是依赖某个具体分配器实现。
+- `ProxyAllocator` 反映了“组合优于继承”的思路：统计逻辑可以叠加在任意底层分配器上。
+- `MemoryManager` 当前更像工厂与引导入口，而不是完整的全局内存分析系统。
 
 ## 头文件
 
-- [Allocator](Allocator/Allocator.md) - `Allocator.h`
+- [Allocator](Allocator/Allocator.md) - `Allocator.h`，分配器抽象接口 `IAllocator`。
-- [LinearAllocator](LinearAllocator/LinearAllocator.md) - `LinearAllocator.h`
+- [LinearAllocator](LinearAllocator/LinearAllocator.md) - `LinearAllocator.h`，线性/arena 风格分配器。
-- [MemoryManager](MemoryManager/MemoryManager.md) - `MemoryManager.h`
+- [MemoryManager](MemoryManager/MemoryManager.md) - `MemoryManager.h`，系统分配器与工厂入口。
-- [PoolAllocator](PoolAllocator/PoolAllocator.md) - `PoolAllocator.h`
+- [PoolAllocator](PoolAllocator/PoolAllocator.md) - `PoolAllocator.h`，固定块池分配器。
-- [ProxyAllocator](ProxyAllocator/ProxyAllocator.md) - `ProxyAllocator.h`
+- [ProxyAllocator](ProxyAllocator/ProxyAllocator.md) - `ProxyAllocator.h`，统计代理分配器。
+
+## 相关指南
+
+- [Allocator Selection And Current Limits](../../_guides/Memory/Allocator-Selection-And-Current-Limits.md) - 解释各分配器适合什么场景、当前实现做到哪一步，以及与商业引擎常见内存策略的关系。
 
 ## 相关文档
 

docs/api/XCEngine/Memory/MemoryManager/CreateLinearAllocator.md

@@ -1,31 +1,39 @@
 # MemoryManager::CreateLinearAllocator
 
-创建新对象或资源。
+创建一个线性分配器。
 
 ```cpp
 std::unique_ptr<LinearAllocator> CreateLinearAllocator(size_t size);
 ```
 
-该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现等价于：
-- `size` - 参数语义详见头文件声明。
-
-**返回：** `std::unique_ptr<LinearAllocator>` - 返回值语义详见头文件声明。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/MemoryManager.h>
+return std::make_unique<LinearAllocator>(size, m_systemAllocator);
-
-void Example() {
-    XCEngine::Memory::MemoryManager object;
-    // 根据上下文补齐参数后调用 MemoryManager::CreateLinearAllocator(...)。
-    (void)object;
-}
 ```
 
+这意味着：
+
+- 如果已经调用过 [Initialize](Initialize.md)，新建的 `LinearAllocator` 会把系统分配器作为父分配器。
+- 如果还没初始化，`m_systemAllocator == nullptr`，`LinearAllocator` 会走自己的直接分配路径。
+
+## 参数
+
+- `size` - 线性缓冲区容量。
+
+## 返回值
+
+- `std::unique_ptr<LinearAllocator>` - 由调用方拥有的线性分配器。
+
+## 生命周期注意事项
+
+- 这个工厂不会把返回对象注册到 `MemoryManager` 内部，调用方仍然负责销毁它。
+- 如果它绑定了系统分配器作为父分配器，应在 [Shutdown](Shutdown.md) 之前销毁；否则析构时可能访问悬空的 `m_systemAllocator`。
+
 ## 相关文档
 
-- [返回类总览](MemoryManager.md)
+- [返回类型总览](MemoryManager.md)
-- [返回模块目录](../Memory.md)
+- [Initialize](Initialize.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/Memory/MemoryManager/CreatePoolAllocator.md

@@ -1,32 +1,36 @@
 # MemoryManager::CreatePoolAllocator
 
-创建新对象或资源。
+创建一个池分配器。
 
 ```cpp
 std::unique_ptr<PoolAllocator> CreatePoolAllocator(size_t blockSize, size_t count);
 ```
 
-该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现等价于：
-- `blockSize` - 参数语义详见头文件声明。
-- `count` - 参数语义详见头文件声明。
-
-**返回：** `std::unique_ptr<PoolAllocator>` - 返回值语义详见头文件声明。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/MemoryManager.h>
+return std::make_unique<PoolAllocator>(blockSize, count);
-
-void Example() {
-    XCEngine::Memory::MemoryManager object;
-    // 根据上下文补齐参数后调用 MemoryManager::CreatePoolAllocator(...)。
-    (void)object;
-}
 ```
 
+它不会使用 `m_systemAllocator`，因此即使没有调用 [Initialize](Initialize.md) 也可以工作。
+
+## 参数
+
+- `blockSize` - 单个逻辑 block 大小。
+- `count` - block 数量。
+
+## 返回值
+
+- `std::unique_ptr<PoolAllocator>` - 由调用方拥有的池分配器。
+
+## 注意事项
+
+- 这个工厂同样只是创建对象，不会集中托管其生命周期。
+- 参数不会在 `MemoryManager` 层做额外校验，`PoolAllocator` 自身当前也缺少防御式检查。
+
 ## 相关文档
 
-- [返回类总览](MemoryManager.md)
+- [返回类型总览](MemoryManager.md)
-- [返回模块目录](../Memory.md)
+- [Initialize](Initialize.md)

docs/api/XCEngine/Memory/MemoryManager/CreateProxyAllocator.md

@@ -1,31 +1,36 @@
 # MemoryManager::CreateProxyAllocator
 
-创建新对象或资源。
+创建一个代理分配器。
 
 ```cpp
 std::unique_ptr<ProxyAllocator> CreateProxyAllocator(const char* name);
 ```
 
-该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现等价于：
-- `name` - 参数语义详见头文件声明。
-
-**返回：** `std::unique_ptr<ProxyAllocator>` - 返回值语义详见头文件声明。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/MemoryManager.h>
+return std::make_unique<ProxyAllocator>(m_systemAllocator, name);
-
-void Example() {
-    XCEngine::Memory::MemoryManager object;
-    // 根据上下文补齐参数后调用 MemoryManager::CreateProxyAllocator(...)。
-    (void)object;
-}
 ```
 
+也就是说，这个工厂当前总是把“系统分配器”作为底层分配器传给 `ProxyAllocator`。
+
+## 参数
+
+- `name` - 代理名称；当前只会把指针原样保存，不会复制内容。
+
+## 返回值
+
+- `std::unique_ptr<ProxyAllocator>` - 由调用方拥有的代理分配器。
+
+## 生命周期注意事项
+
+- 应在 [Initialize](Initialize.md) 之后调用；否则底层分配器为空，后续任何分配操作都可能触发未定义行为。
+- 应在 [Shutdown](Shutdown.md) 之前销毁；否则底层系统分配器被删除后，代理内部会留下悬空指针。
+
 ## 相关文档
 
-- [返回类总览](MemoryManager.md)
+- [返回类型总览](MemoryManager.md)
-- [返回模块目录](../Memory.md)
+- [Initialize](Initialize.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/Memory/MemoryManager/DumpMemoryLeaks.md

@@ -1,30 +1,26 @@
 # MemoryManager::DumpMemoryLeaks
 
-公开方法，详见头文件声明。
+输出内存泄漏报告。
 
 ```cpp
 void DumpMemoryLeaks();
 ```
 
-该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现还只是占位接口，实际只向标准输出打印一行标题：
-
-**返回：** `void` - 无返回值。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/MemoryManager.h>
+Memory Leak Report:
-
-void Example() {
-    XCEngine::Memory::MemoryManager object;
-    // 根据上下文补齐参数后调用 MemoryManager::DumpMemoryLeaks(...)。
-    (void)object;
-}
 ```
 
+它不会遍历任何分配记录，也不会列出真实泄漏条目。
+
+## 返回值
+
+- 无。
+
 ## 相关文档
 
-- [返回类总览](MemoryManager.md)
+- [返回类型总览](MemoryManager.md)
-- [返回模块目录](../Memory.md)
+- [GenerateMemoryReport](GenerateMemoryReport.md)

docs/api/XCEngine/Memory/MemoryManager/GenerateMemoryReport.md

@@ -1,30 +1,26 @@
 # MemoryManager::GenerateMemoryReport
 
-公开方法，详见头文件声明。
+输出内存报告。
 
 ```cpp
 void GenerateMemoryReport();
 ```
 
-该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现同样只是占位接口，实际只向标准输出打印：
-
-**返回：** `void` - 无返回值。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/MemoryManager.h>
+Memory Report:
-
-void Example() {
-    XCEngine::Memory::MemoryManager object;
-    // 根据上下文补齐参数后调用 MemoryManager::GenerateMemoryReport(...)。
-    (void)object;
-}
 ```
 
+它不会汇总各分配器状态，也不会生成结构化报表文件。
+
+## 返回值
+
+- 无。
+
 ## 相关文档
 
-- [返回类总览](MemoryManager.md)
+- [返回类型总览](MemoryManager.md)
-- [返回模块目录](../Memory.md)
+- [DumpMemoryLeaks](DumpMemoryLeaks.md)

docs/api/XCEngine/Memory/MemoryManager/Get.md

@@ -1,29 +1,29 @@
 # MemoryManager::Get
 
-获取相关状态或对象。
+获取全局 `MemoryManager` 单例。
 
 ```cpp
 static MemoryManager& Get();
 ```
 
-该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现通过函数内静态对象返回进程级唯一实例：
-
-**返回：** `MemoryManager&` - 返回值语义详见头文件声明。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/MemoryManager.h>
+static MemoryManager instance;
-
-void Example() {
-    auto& instance = XCEngine::Memory::MemoryManager::Get();
-    (void)instance;
-}
 ```
 
+## 返回值
+
+- `MemoryManager&` - 全局 `MemoryManager` 实例引用。
+
+## 设计说明
+
+- 这提供了一个集中入口，但不意味着所有分配器对象都被统一托管。
+- 通过工厂方法创建出来的分配器，生命周期仍由调用方负责。
+
 ## 相关文档
 
-- [返回类总览](MemoryManager.md)
+- [返回类型总览](MemoryManager.md)
-- [返回模块目录](../Memory.md)
+- [Initialize](Initialize.md)

docs/api/XCEngine/Memory/MemoryManager/GetSystemAllocator.md

@@ -1,30 +1,26 @@
 # MemoryManager::GetSystemAllocator
 
-获取相关状态或对象。
+获取内部系统分配器。
 
 ```cpp
 IAllocator* GetSystemAllocator();
 ```
 
-该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现直接返回成员指针 `m_systemAllocator`，不会增加引用计数，也不会转移所有权。
 
-**返回：** `IAllocator*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `IAllocator*` - 系统分配器指针；未初始化或已关闭时为 `nullptr`。
 
-```cpp
+## 生命周期注意事项
-#include <XCEngine/Memory/MemoryManager.h>
 
-void Example() {
+- 这是一个非拥有指针。
-    XCEngine::Memory::MemoryManager object;
+- 只有在 [Initialize](Initialize.md) 之后、[Shutdown](Shutdown.md) 之前使用才安全。
-    // 根据上下文补齐参数后调用 MemoryManager::GetSystemAllocator(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](MemoryManager.md)
+- [返回类型总览](MemoryManager.md)
-- [返回模块目录](../Memory.md)
+- [Initialize](Initialize.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/Memory/MemoryManager/Initialize.md

@@ -1,30 +1,31 @@
 # MemoryManager::Initialize
 
-初始化内部状态。
+初始化内部系统分配器。
 
 ```cpp
 void Initialize();
 ```
 
-该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现是幂等的：
 
-**返回：** `void` - 无返回值。
+1. 如果 `m_initialized` 已经是 `true`，直接返回。
+2. 否则执行 `m_systemAllocator = new SystemAllocator();`
+3. 把 `m_initialized` 设为 `true`。
 
-**示例：**
+## 返回值
 
-```cpp
+- 无。
-#include <XCEngine/Memory/MemoryManager.h>
 
-void Example() {
+## 当前实现限制
-    XCEngine::Memory::MemoryManager object;
+
-    // 根据上下文补齐参数后调用 MemoryManager::Initialize(...)。
+- 不加锁，不适合并发初始化。
-    (void)object;
+- 不处理 `new SystemAllocator()` 失败后的恢复逻辑。
-}
+- 不会因为 `m_trackAllocations` 的值不同而启用额外跟踪流程。
-```
 
 ## 相关文档
 
-- [返回类总览](MemoryManager.md)
+- [返回类型总览](MemoryManager.md)
-- [返回模块目录](../Memory.md)
+- [GetSystemAllocator](GetSystemAllocator.md)
+- [Shutdown](Shutdown.md)

docs/api/XCEngine/Memory/MemoryManager/MemoryManager.md

@@ -6,34 +6,57 @@
 
 **头文件**: `XCEngine/Memory/MemoryManager.h`
 
-**描述**: 定义 `XCEngine/Memory` 子目录中的 `MemoryManager` public API。
+**描述**: 初始化内部系统分配器，并提供常用分配器的工厂接口。
 
 ## 概述
 
-`MemoryManager.h` 是 `XCEngine/Memory` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`MemoryManager` 当前是内存模块的全局入口，但它的职责比名字听起来更窄。它主要做三件事：
 
-## 声明概览
+- 创建和保存一个内部 `SystemAllocator`
+- 提供若干分配器工厂方法
+- 预留追踪、泄漏报告和报表接口
 
-| 声明 | 类型 | 说明 |
+它还定义了两个便利宏：
-|------|------|------|
-| `MemoryManager` | `class` | 头文件中的公开声明。 |
 
-## 公共方法
+- `XE_ALLOC(allocator, size, ...)`
+- `XE_FREE(allocator, ptr)`
 
-| 方法 | 描述 |
+## 当前实现边界
+
+- 只有在 [Initialize](Initialize.md) 之后，`GetSystemAllocator()` 才会返回有效系统分配器。
+- `CreateLinearAllocator()` 即使在未初始化时也能工作，因为 `LinearAllocator` 在父分配器为空时会走自身的直接分配路径。
+- `CreateProxyAllocator()` 在未初始化时会创建一个底层分配器为空的对象，后续实际分配将产生未定义行为，因此应在初始化后使用。
+- 使用系统分配器作为底层或父分配器创建出来的对象，应在 [Shutdown](Shutdown.md) 之前销毁，否则会留下悬空指针。
+- `SetTrackAllocations()` 当前只修改标志位，不驱动统计逻辑。
+- `DumpMemoryLeaks()` 和 `GenerateMemoryReport()` 当前只向 `stdout` 输出标题。
+
+## 生命周期
+
+- [Get](Get.md) 返回进程级单例。
+- [Initialize](Initialize.md) 创建内部系统分配器。
+- [Shutdown](Shutdown.md) 销毁内部系统分配器。
+
+## 线程语义
+
+- 当前管理器自身没有锁。
+- 建议在启动和受控退出阶段使用，不要在多个线程中并发初始化或关闭。
+
+## 公开方法
+
+| 方法 | 说明 |
 |------|------|
-| [Get](Get.md) | 获取相关状态或对象。 |
+| [Get](Get.md) | 获取全局 `MemoryManager` 实例。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
+| [Initialize](Initialize.md) | 初始化内存管理器。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
+| [Shutdown](Shutdown.md) | 关闭内存管理器。 |
-| [GetSystemAllocator](GetSystemAllocator.md) | 获取相关状态或对象。 |
+| [GetSystemAllocator](GetSystemAllocator.md) | 获取内部系统分配器。 |
-| [CreateLinearAllocator](CreateLinearAllocator.md) | 创建新对象或资源。 |
+| [CreateLinearAllocator](CreateLinearAllocator.md) | 创建线性分配器。 |
-| [CreatePoolAllocator](CreatePoolAllocator.md) | 创建新对象或资源。 |
+| [CreatePoolAllocator](CreatePoolAllocator.md) | 创建池分配器。 |
-| [CreateProxyAllocator](CreateProxyAllocator.md) | 创建新对象或资源。 |
+| [CreateProxyAllocator](CreateProxyAllocator.md) | 创建代理分配器。 |
-| [SetTrackAllocations](SetTrackAllocations.md) | 设置相关状态或配置。 |
+| [SetTrackAllocations](SetTrackAllocations.md) | 设置是否跟踪分配；当前仅保存标志位。 |
-| [DumpMemoryLeaks](DumpMemoryLeaks.md) | 公开方法，详见头文件声明。 |
+| [DumpMemoryLeaks](DumpMemoryLeaks.md) | 输出泄漏报告标题。 |
-| [GenerateMemoryReport](GenerateMemoryReport.md) | 公开方法，详见头文件声明。 |
+| [GenerateMemoryReport](GenerateMemoryReport.md) | 输出内存报告标题。 |
 
 ## 相关文档
 
-- [当前目录](../Memory.md) - 返回 `Memory` 平行目录
+- [当前模块](../Memory.md)
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [Allocator Selection And Current Limits](../../../_guides/Memory/Allocator-Selection-And-Current-Limits.md)

docs/api/XCEngine/Memory/MemoryManager/SetTrackAllocations.md

@@ -1,31 +1,30 @@
 # MemoryManager::SetTrackAllocations
 
-设置相关状态或配置。
+设置是否跟踪分配。
 
 ```cpp
 void SetTrackAllocations(bool track);
 ```
 
-该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现只做一件事：
-- `track` - 参数语义详见头文件声明。
-
-**返回：** `void` - 无返回值。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/MemoryManager.h>
+m_trackAllocations = track;
-
-void Example() {
-    XCEngine::Memory::MemoryManager object;
-    // 根据上下文补齐参数后调用 MemoryManager::SetTrackAllocations(...)。
-    (void)object;
-}
 ```
 
+它不会创建追踪器、不会改变 `ProxyAllocator` 行为，也不会影响 `DumpMemoryLeaks()` 或 `GenerateMemoryReport()` 的输出内容。
+
+## 参数
+
+- `track` - 要保存的跟踪开关值。
+
+## 返回值
+
+- 无。
+
 ## 相关文档
 
-- [返回类总览](MemoryManager.md)
+- [返回类型总览](MemoryManager.md)
-- [返回模块目录](../Memory.md)
+- [DumpMemoryLeaks](DumpMemoryLeaks.md)

docs/api/XCEngine/Memory/MemoryManager/Shutdown.md

@@ -1,30 +1,31 @@
 # MemoryManager::Shutdown
 
-关闭并清理内部状态。
+关闭内存管理器并销毁内部系统分配器。
 
 ```cpp
 void Shutdown();
 ```
 
-该方法声明于 `XCEngine/Memory/MemoryManager.h`，当前页面用于固定 `MemoryManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现也是幂等的：
 
-**返回：** `void` - 无返回值。
+1. 如果 `m_initialized` 为 `false`，直接返回。
+2. 否则执行 `delete static_cast<SystemAllocator*>(m_systemAllocator);`
+3. 把 `m_systemAllocator` 置空，并把 `m_initialized` 设为 `false`。
 
-**示例：**
+## 返回值
 
-```cpp
+- 无。
-#include <XCEngine/Memory/MemoryManager.h>
 
-void Example() {
+## 当前实现限制
-    XCEngine::Memory::MemoryManager object;
+
-    // 根据上下文补齐参数后调用 MemoryManager::Shutdown(...)。
+- 不会自动销毁通过工厂方法创建的其它分配器对象。
-    (void)object;
+- 不会检查是否还有未释放对象或未完成的泄漏跟踪。
-}
+- 如果仍有依赖系统分配器的 `LinearAllocator` 或 `ProxyAllocator` 存活，后续使用或析构都可能访问悬空指针。
-```
 
 ## 相关文档
 
-- [返回类总览](MemoryManager.md)
+- [返回类型总览](MemoryManager.md)
-- [返回模块目录](../Memory.md)
+- [Initialize](Initialize.md)
+- [GetSystemAllocator](GetSystemAllocator.md)

docs/api/XCEngine/Memory/PoolAllocator/Allocate.md

@@ -1,32 +1,43 @@
 # PoolAllocator::Allocate
 
-公开方法，详见头文件声明。
+从空闲链表中取出一个固定块。
 
 ```cpp
 void* Allocate(size_t size, size_t alignment = 0) override;
 ```
 
-该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现按以下顺序执行：
-- `size` - 参数语义详见头文件声明。
-- `alignment` - 参数语义详见头文件声明。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+1. 如果空闲链表为空，返回 `nullptr`。
+2. 如果 `size > m_blockSize`，返回 `nullptr`。
+3. 取出链表头节点，把 `m_freeBlocks` 减一。
+4. 直接返回该节点地址。
 
-**示例：**
+需要特别注意：
 
-```cpp
+- `alignment` 参数在当前实现中被完全忽略。
-#include <XCEngine/Memory/PoolAllocator.h>
+- 只要 `size <= m_blockSize`，调用就会占用整个 block；不会按请求大小切分。
+- `size == 0` 也会消耗一个 block。
+- 返回地址来自构造阶段预先切好的池，不会在调用时再次向系统堆申请内存。
 
-void Example() {
+## 参数
-    XCEngine::Memory::PoolAllocator object;
+
-    // 根据上下文补齐参数后调用 PoolAllocator::Allocate(...)。
+- `size` - 请求大小；必须不大于构造时的 `blockSize`。
-    (void)object;
+- `alignment` - 调用期对齐要求；当前实现不使用它。
-}
+
-```
+## 返回值
+
+- `void*` - 成功时返回一个 block 的起始地址；池已耗尽或请求过大时返回 `nullptr`。
+
+## 使用建议
+
+- 把 `size` 理解为“上界检查”而不是“真实占用字节数”。
+- 如果调用方依赖逐次调用时的不同对齐要求，当前实现并不满足这种需求。
 
 ## 相关文档
 
-- [返回类总览](PoolAllocator.md)
+- [返回类型总览](PoolAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Free](Free.md)
+- [Contains](Contains.md)

docs/api/XCEngine/Memory/PoolAllocator/Constructor.md

@@ -1,31 +1,45 @@
-# PoolAllocator::PoolAllocator()
+# PoolAllocator::Constructor
 
-构造对象。
+构造一个固定块池分配器。
 
 ```cpp
 PoolAllocator(size_t blockSize, size_t poolSize, size_t alignment = 8);
 ```
 
-该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+构造函数会一次性完成两件事：
-- `blockSize` - 参数语义详见头文件声明。
-- `poolSize` - 参数语义详见头文件声明。
-- `alignment` - 参数语义详见头文件声明。
 
-**返回：** `void` - 无返回值。
+1. 计算每个 block 的实际步长 `actualBlockSize`。
+2. 申请一整块池内存，并把它串成单向空闲链表。
 
-**示例：**
+当 `alignment > 0` 时，当前实现使用下面的位运算向上取整：
 
 ```cpp
-#include <XCEngine/Memory/PoolAllocator.h>
+(blockSize + alignment - 1) & ~(alignment - 1)
-
-void Example() {
-    XCEngine::Memory::PoolAllocator object;
-}
 ```
 
+随后它会调用 `std::malloc(actualBlockSize * poolSize)`，并在这块连续内存上建立空闲链表。
+
+## 参数
+
+- `blockSize` - 逻辑 block 大小，也是 [Allocate](Allocate.md) 允许的最大请求大小。
+- `poolSize` - block 数量。
+- `alignment` - block 步长对齐粒度；默认值为 `8`。
+
+## 返回值
+
+- 无。
+
+## 当前实现限制
+
+- 当前没有验证 `alignment` 是否是 2 的幂。
+- 当前没有防御 `blockSize == 0`、`poolSize == 0` 或底层分配失败。
+- 在 `poolSize == 0` 或 `malloc` 失败时，后续空闲链表初始化可能进入未定义行为，因此调用方应保证参数有效。
+- 对齐只影响 block 步长，不保证 `malloc` 返回的池起始地址本身满足同样的高阶对齐要求。
+
 ## 相关文档
 
-- [返回类总览](PoolAllocator.md)
+- [返回类型总览](PoolAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Destructor](Destructor.md)
+- [GetBlockSize](GetBlockSize.md)

docs/api/XCEngine/Memory/PoolAllocator/Contains.md

@@ -1,31 +1,36 @@
 # PoolAllocator::Contains
 
-公开方法，详见头文件声明。
+判断指针是否落在当前池的地址范围内。
 
 ```cpp
 bool Contains(void* ptr) const;
 ```
 
-该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现只做范围判断：
-- `ptr` - 参数语义详见头文件声明。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+1. 如果 `ptr == nullptr` 或 `m_memory == nullptr`，返回 `false`。
+2. 计算 `ptr` 相对池起始地址的偏移。
+3. 用构造阶段的实际 block 步长乘以 `m_totalBlocks`，得到整个池的地址范围。
+4. 只要偏移仍在这个范围内，就返回 `true`。
 
-**示例：**
+这意味着：
 
-```cpp
+- 它是范围检查，不是“当前已分配块”的检查。
-#include <XCEngine/Memory/PoolAllocator.h>
+- 指向某个 block 中间位置的指针也可能返回 `true`。
+- 已经释放回池的指针仍可能返回 `true`。
+- 它不验证指针是否落在 block 边界上。
 
-void Example() {
+## 参数
-    XCEngine::Memory::PoolAllocator object;
+
-    // 根据上下文补齐参数后调用 PoolAllocator::Contains(...)。
+- `ptr` - 待检测指针。
-    (void)object;
+
-}
+## 返回值
-```
+
+- `bool` - 指针位于池地址范围内时返回 `true`；否则返回 `false`。
 
 ## 相关文档
 
-- [返回类总览](PoolAllocator.md)
+- [返回类型总览](PoolAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Free](Free.md)

docs/api/XCEngine/Memory/PoolAllocator/Destructor.md

@@ -1,29 +1,31 @@
-# PoolAllocator::~PoolAllocator()
+# PoolAllocator::Destructor
 
-销毁对象并释放相关资源。
+销毁整个池并释放底层大块内存。
 
 ```cpp
 ~PoolAllocator() override;
 ```
 
-该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现只做一件事：
-
-**返回：** `void` - 无返回值。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/PoolAllocator.h>
+std::free(m_memory);
-
-void Example() {
-    XCEngine::Memory::PoolAllocator object;
-    // 对象离开作用域时会自动触发析构。
-}
 ```
 
+它不会遍历池中的对象，也不会为池中存放的 C++ 对象调用析构函数。换句话说，`PoolAllocator` 只负责原始内存块，不负责对象生命周期管理。
+
+## 返回值
+
+- 无。
+
+## 使用建议
+
+- 如果 block 中放的是需要析构的对象，应由调用方先显式析构对象，再销毁分配器。
+- 分配器销毁后，之前返回的所有 block 指针都会变成悬空指针。
+
 ## 相关文档
 
-- [返回类总览](PoolAllocator.md)
+- [返回类型总览](PoolAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Free](Free.md)

docs/api/XCEngine/Memory/PoolAllocator/Free.md

@@ -1,31 +1,38 @@
 # PoolAllocator::Free
 
-公开方法，详见头文件声明。
+把一个 block 放回空闲链表。
 
 ```cpp
 void Free(void* ptr) override;
 ```
 
-该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现非常直接：
-- `ptr` - 参数语义详见头文件声明。
 
-**返回：** `void` - 无返回值。
+1. 如果 `ptr == nullptr`，直接返回。
+2. 把 `ptr` 视为 `FreeNode*`。
+3. 把该节点插回空闲链表头部。
+4. 把 `m_freeBlocks` 加一。
 
-**示例：**
+## 参数
 
-```cpp
+- `ptr` - 要归还的 block 指针。
-#include <XCEngine/Memory/PoolAllocator.h>
 
-void Example() {
+## 返回值
-    XCEngine::Memory::PoolAllocator object;
+
-    // 根据上下文补齐参数后调用 PoolAllocator::Free(...)。
+- 无。
-    (void)object;
+
-}
+## 当前实现限制
-```
+
+- 不验证 `ptr` 是否真的来自当前池。
+- 不验证 `ptr` 是否位于 block 边界。
+- 不防止重复释放。
+- 如果把不属于当前池的地址传进来，可能破坏空闲链表甚至直接写坏任意内存。
+- 如果重复释放同一块，`m_freeBlocks` 可能大于 `m_totalBlocks`，随后统计接口会失真甚至发生无符号下溢。
 
 ## 相关文档
 
-- [返回类总览](PoolAllocator.md)
+- [返回类型总览](PoolAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Allocate](Allocate.md)
+- [Contains](Contains.md)

docs/api/XCEngine/Memory/PoolAllocator/GetAllocationCount.md

@@ -1,30 +1,31 @@
 # PoolAllocator::GetAllocationCount
 
-获取相关状态或对象。
+查询当前已分配 block 数量。
 
 ```cpp
 size_t GetAllocationCount() const override;
 ```
 
-该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现返回：
-
-**返回：** `size_t` - 返回值语义详见头文件声明。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/PoolAllocator.h>
+m_totalBlocks - m_freeBlocks
-
-void Example() {
-    XCEngine::Memory::PoolAllocator object;
-    // 根据上下文补齐参数后调用 PoolAllocator::GetAllocationCount(...)。
-    (void)object;
-}
 ```
 
+这反映的是“当前在用 block 数”，不是累计分配次数。
+
+## 返回值
+
+- `size_t` - 当前在用 block 数。
+
+## 注意事项
+
+- 这个值依赖 [Free](Free.md) 正确维护 `m_freeBlocks`。
+- 如果发生重复释放或错误释放，`m_freeBlocks` 可能超过 `m_totalBlocks`，此处会出现无符号下溢并返回失真的大数值。
+
 ## 相关文档
 
-- [返回类总览](PoolAllocator.md)
+- [返回类型总览](PoolAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetFreeBlockCount](GetFreeBlockCount.md)

docs/api/XCEngine/Memory/PoolAllocator/GetBlockSize.md

@@ -1,30 +1,27 @@
 # PoolAllocator::GetBlockSize
 
-获取相关状态或对象。
+查询逻辑 block 大小。
 
 ```cpp
 size_t GetBlockSize() const;
 ```
 
-该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回 `m_blockSize`。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+这表示的是 API 视角下的单块容量上限，也就是 [Allocate](Allocate.md) 允许的最大请求大小；它不一定等于构造时实际使用的 block 步长。
 
-**示例：**
+## 返回值
 
-```cpp
+- `size_t` - 逻辑 block 大小。
-#include <XCEngine/Memory/PoolAllocator.h>
 
-void Example() {
+## 注意事项
-    XCEngine::Memory::PoolAllocator object;
+
-    // 根据上下文补齐参数后调用 PoolAllocator::GetBlockSize(...)。
+- 如果构造时传入了较大的 `alignment`，实际池内存的 block 间距可能大于这里返回的值。
-    (void)object;
+- [GetTotalAllocated](GetTotalAllocated.md)、[GetTotalFreed](GetTotalFreed.md) 和 [GetPeakAllocated](GetPeakAllocated.md) 也都是基于这个逻辑大小计算，而不是基于实际 stride。
-}
-```
 
 ## 相关文档
 
-- [返回类总览](PoolAllocator.md)
+- [返回类型总览](PoolAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Constructor](Constructor.md)

docs/api/XCEngine/Memory/PoolAllocator/GetFreeBlockCount.md

@@ -1,30 +1,25 @@
 # PoolAllocator::GetFreeBlockCount
 
-获取相关状态或对象。
+查询当前空闲 block 数。
 
 ```cpp
 size_t GetFreeBlockCount() const;
 ```
 
-该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现直接返回 `m_freeBlocks`。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `size_t` - 当前空闲 block 数。
 
-```cpp
+## 注意事项
-#include <XCEngine/Memory/PoolAllocator.h>
 
-void Example() {
+- 这是一个“当前快照值”，不是历史统计。
-    XCEngine::Memory::PoolAllocator object;
+- 如果调用方错误地传入无效指针或重复释放，`m_freeBlocks` 会被破坏，这里的结果也会随之失真。
-    // 根据上下文补齐参数后调用 PoolAllocator::GetFreeBlockCount(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](PoolAllocator.md)
+- [返回类型总览](PoolAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetAllocationCount](GetAllocationCount.md)

docs/api/XCEngine/Memory/PoolAllocator/GetName.md

@@ -1,30 +1,23 @@
 # PoolAllocator::GetName
 
-获取相关状态或对象。
+查询分配器名称。
 
 ```cpp
 const char* GetName() const override;
 ```
 
-该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现固定返回字符串字面量：
-
-**返回：** `const char*` - 返回值语义详见头文件声明。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/PoolAllocator.h>
+"PoolAllocator"
-
-void Example() {
-    XCEngine::Memory::PoolAllocator object;
-    // 根据上下文补齐参数后调用 PoolAllocator::GetName(...)。
-    (void)object;
-}
 ```
 
+## 返回值
+
+- `const char*` - 当前固定为 `"PoolAllocator"`。
+
 ## 相关文档
 
-- [返回类总览](PoolAllocator.md)
+- [返回类型总览](PoolAllocator.md)
-- [返回模块目录](../Memory.md)

docs/api/XCEngine/Memory/PoolAllocator/GetPeakAllocated.md

@@ -1,30 +1,31 @@
 # PoolAllocator::GetPeakAllocated
 
-获取相关状态或对象。
+查询峰值分配量。
 
 ```cpp
 size_t GetPeakAllocated() const override;
 ```
 
-该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现返回：
-
-**返回：** `size_t` - 返回值语义详见头文件声明。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/PoolAllocator.h>
+m_totalBlocks * m_blockSize
-
-void Example() {
-    XCEngine::Memory::PoolAllocator object;
-    // 根据上下文补齐参数后调用 PoolAllocator::GetPeakAllocated(...)。
-    (void)object;
-}
 ```
 
+这并不是“历史上曾经达到过的最大已用字节数”，而是整个池按逻辑 block 大小计算的总容量上界。
+
+## 返回值
+
+- `size_t` - 当前实现下等于总池容量上界。
+
+## 注意事项
+
+- 如果你把它当作调试统计里的“历史峰值”，会得到过于乐观的结果。
+- 这里同样不考虑对齐放大后的真实 stride。
+
 ## 相关文档
 
-- [返回类总览](PoolAllocator.md)
+- [返回类型总览](PoolAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetTotalAllocated](GetTotalAllocated.md)

docs/api/XCEngine/Memory/PoolAllocator/GetTotalAllocated.md

@@ -1,30 +1,31 @@
 # PoolAllocator::GetTotalAllocated
 
-获取相关状态或对象。
+查询当前已用字节数。
 
 ```cpp
 size_t GetTotalAllocated() const override;
 ```
 
-该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现返回：
-
-**返回：** `size_t` - 返回值语义详见头文件声明。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/PoolAllocator.h>
+(m_totalBlocks - m_freeBlocks) * m_blockSize
-
-void Example() {
-    XCEngine::Memory::PoolAllocator object;
-    // 根据上下文补齐参数后调用 PoolAllocator::GetTotalAllocated(...)。
-    (void)object;
-}
 ```
 
+因此它表示的是“当前正在使用的逻辑字节数”，而不是累计分配过多少字节。
+
+## 返回值
+
+- `size_t` - 当前已用逻辑字节数。
+
+## 注意事项
+
+- 这里按 `m_blockSize` 计费，不按对齐后的实际 stride 计费。
+- 如果 `m_freeBlocks` 因错误释放被破坏，这个值也会失真。
+
 ## 相关文档
 
-- [返回类总览](PoolAllocator.md)
+- [返回类型总览](PoolAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetTotalFreed](GetTotalFreed.md)

docs/api/XCEngine/Memory/PoolAllocator/GetTotalBlockCount.md

@@ -1,30 +1,20 @@
 # PoolAllocator::GetTotalBlockCount
 
-获取相关状态或对象。
+查询池中的总 block 数。
 
 ```cpp
 size_t GetTotalBlockCount() const;
 ```
 
-该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回 `m_totalBlocks`，也就是构造时指定的 block 数量。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `size_t` - 池的总 block 数。
-
-```cpp
-#include <XCEngine/Memory/PoolAllocator.h>
-
-void Example() {
-    XCEngine::Memory::PoolAllocator object;
-    // 根据上下文补齐参数后调用 PoolAllocator::GetTotalBlockCount(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](PoolAllocator.md)
+- [返回类型总览](PoolAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetFreeBlockCount](GetFreeBlockCount.md)

docs/api/XCEngine/Memory/PoolAllocator/GetTotalFreed.md

@@ -1,30 +1,31 @@
 # PoolAllocator::GetTotalFreed
 
-获取相关状态或对象。
+查询当前空闲字节数。
 
 ```cpp
 size_t GetTotalFreed() const override;
 ```
 
-该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现返回：
-
-**返回：** `size_t` - 返回值语义详见头文件声明。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/PoolAllocator.h>
+m_freeBlocks * m_blockSize
-
-void Example() {
-    XCEngine::Memory::PoolAllocator object;
-    // 根据上下文补齐参数后调用 PoolAllocator::GetTotalFreed(...)。
-    (void)object;
-}
 ```
 
+因此这个接口在 `PoolAllocator` 中表示的是“当前还空着多少逻辑字节”，不是“累计向系统释放了多少字节”。整个池在分配器存活期间始终保留在进程内存中，直到析构时才统一释放。
+
+## 返回值
+
+- `size_t` - 当前空闲逻辑字节数。
+
+## 注意事项
+
+- 这里同样不考虑对齐放大的真实 stride。
+- 如果发生错误释放，`m_freeBlocks` 失真，这里的统计也会随之失真。
+
 ## 相关文档
 
-- [返回类总览](PoolAllocator.md)
+- [返回类型总览](PoolAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetTotalAllocated](GetTotalAllocated.md)

docs/api/XCEngine/Memory/PoolAllocator/PoolAllocator.md

@@ -6,38 +6,57 @@
 
 **头文件**: `XCEngine/Memory/PoolAllocator.h`
 
-**描述**: 定义 `XCEngine/Memory` 子目录中的 `PoolAllocator` public API。
+**描述**: 为固定尺寸对象提供 O(1) 弹出/归还的池分配器。
 
 ## 概述
 
-`PoolAllocator.h` 是 `XCEngine/Memory` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`PoolAllocator` 预先申请一整块内存，然后把它切成固定尺寸的 block，通过空闲链表管理这些 block。它适合：
 
-## 声明概览
+- 大量尺寸相同或尺寸上界稳定的小对象
+- 频繁分配和释放、但不想承担通用堆分配碎片与额外元数据开销的场景
 
-| 声明 | 类型 | 说明 |
+## 生命周期与所有权
-|------|------|------|
-| `PoolAllocator` | `class` | 继承自 `IAllocator` 的公开声明。 |
 
-## 公共方法
+- [Constructor](Constructor.md) 一次性申请整个池。
+- [Allocate](Allocate.md) 从空闲链表弹出一个 block。
+- [Free](Free.md) 把 block 放回空闲链表头部。
+- [Destructor](Destructor.md) 在整个池销毁时一次性释放底层内存。
 
-| 方法 | 描述 |
+## 当前实现限制
+
+- [Reallocate](Reallocate.md) 当前返回 `nullptr`。
+- `Allocate` 忽略调用时传入的 `alignment` 参数，真正使用的是构造阶段保存的对齐设置。
+- 对齐逻辑当前只影响 block stride 计算，不保证底层池起始地址本身按该对齐值申请。
+- 构造函数当前不校验 `blockSize > 0`、`poolSize > 0`，也不处理底层内存申请失败后的初始化路径。
+- [Free](Free.md) 不检查指针是否真的来自当前池，也不防止重复释放。
+- [Contains](Contains.md) 当前只检查“是否落在池的地址范围内”，不检查是否对齐到 block 边界，也不检查块是否仍在分配状态。
+- `GetPeakAllocated` 当前返回整个池的总容量，而不是历史峰值使用量。
+
+## 线程语义
+
+- 当前没有锁；需要外部同步。
+
+## 公开方法
+
+| 方法 | 说明 |
 |------|------|
-| [PoolAllocator()](Constructor.md) | 构造对象。 |
+| [Constructor](Constructor.md) | 构造固定块池分配器。 |
-| [~PoolAllocator()](Destructor.md) | 销毁对象并释放相关资源。 |
+| [Destructor](Destructor.md) | 销毁整个池。 |
-| [Allocate](Allocate.md) | 公开方法，详见头文件声明。 |
+| [Allocate](Allocate.md) | 分配一个 block。 |
-| [Free](Free.md) | 公开方法，详见头文件声明。 |
+| [Free](Free.md) | 归还一个 block。 |
-| [Reallocate](Reallocate.md) | 公开方法，详见头文件声明。 |
+| [Reallocate](Reallocate.md) | 重分配 block；当前返回 `nullptr`。 |
-| [Contains](Contains.md) | 公开方法，详见头文件声明。 |
+| [Contains](Contains.md) | 判断指针是否位于池地址范围内。 |
-| [GetBlockSize](GetBlockSize.md) | 获取相关状态或对象。 |
+| [GetBlockSize](GetBlockSize.md) | 查询逻辑 block 大小。 |
-| [GetFreeBlockCount](GetFreeBlockCount.md) | 获取相关状态或对象。 |
+| [GetFreeBlockCount](GetFreeBlockCount.md) | 查询空闲 block 数。 |
-| [GetTotalBlockCount](GetTotalBlockCount.md) | 获取相关状态或对象。 |
+| [GetTotalBlockCount](GetTotalBlockCount.md) | 查询总 block 数。 |
-| [GetName](GetName.md) | 获取相关状态或对象。 |
+| [GetName](GetName.md) | 查询分配器名称。 |
-| [GetTotalAllocated](GetTotalAllocated.md) | 获取相关状态或对象。 |
+| [GetTotalAllocated](GetTotalAllocated.md) | 查询当前已用字节数。 |
-| [GetTotalFreed](GetTotalFreed.md) | 获取相关状态或对象。 |
+| [GetTotalFreed](GetTotalFreed.md) | 查询当前空闲字节数。 |
-| [GetPeakAllocated](GetPeakAllocated.md) | 获取相关状态或对象。 |
+| [GetPeakAllocated](GetPeakAllocated.md) | 查询峰值分配量；当前返回总池容量。 |
-| [GetAllocationCount](GetAllocationCount.md) | 获取相关状态或对象。 |
+| [GetAllocationCount](GetAllocationCount.md) | 查询当前已分配 block 数。 |
 
 ## 相关文档
 
-- [当前目录](../Memory.md) - 返回 `Memory` 平行目录
+- [当前模块](../Memory.md)
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [IAllocator](../Allocator/Allocator.md)
+- [Allocator Selection And Current Limits](../../../_guides/Memory/Allocator-Selection-And-Current-Limits.md)

docs/api/XCEngine/Memory/PoolAllocator/Reallocate.md

@@ -1,32 +1,29 @@
 # PoolAllocator::Reallocate
 
-公开方法，详见头文件声明。
+重分配一个 block。
 
 ```cpp
 void* Reallocate(void* ptr, size_t newSize) override;
 ```
 
-该方法声明于 `XCEngine/Memory/PoolAllocator.h`，当前页面用于固定 `PoolAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现没有真正支持可变尺寸重分配，函数体固定返回 `nullptr`，也不会读取 `ptr` 或 `newSize`。
-- `ptr` - 参数语义详见头文件声明。
-- `newSize` - 参数语义详见头文件声明。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `ptr` - 原 block 指针；当前实现忽略。
+- `newSize` - 新大小；当前实现忽略。
 
-```cpp
+## 返回值
-#include <XCEngine/Memory/PoolAllocator.h>
 
-void Example() {
+- `void*` - 当前固定返回 `nullptr`。
-    XCEngine::Memory::PoolAllocator object;
+
-    // 根据上下文补齐参数后调用 PoolAllocator::Reallocate(...)。
+## 设计说明
-    (void)object;
+
-}
+这与池分配器的典型定位一致：它更适合固定尺寸对象，而不是 `realloc` 风格的可变尺寸缓冲。
-```
 
 ## 相关文档
 
-- [返回类总览](PoolAllocator.md)
+- [返回类型总览](PoolAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Allocate](Allocate.md)

docs/api/XCEngine/Memory/ProxyAllocator/Allocate.md

@@ -1,32 +1,39 @@
 # ProxyAllocator::Allocate
 
-公开方法，详见头文件声明。
+通过底层分配器申请内存，并更新代理统计。
 
 ```cpp
 void* Allocate(size_t size, size_t alignment = 0) override;
 ```
 
-该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现会先加锁，然后执行以下逻辑：
-- `size` - 参数语义详见头文件声明。
-- `alignment` - 参数语义详见头文件声明。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+1. 调用 `m_underlying->Allocate(size, alignment)`。
+2. 如果返回非空：
+   - `m_stats.totalAllocated += size`
+   - `m_stats.allocationCount++`
+   - 用 `m_stats.totalAllocated - m_stats.totalFreed` 更新 `m_stats.peakAllocated`
+3. 返回底层分配器给出的指针。
 
-**示例：**
+## 参数
 
-```cpp
+- `size` - 请求大小；成功时会按这个值计入 `totalAllocated`。
-#include <XCEngine/Memory/ProxyAllocator.h>
+- `alignment` - 对齐要求；当前只是原样转发到底层分配器。
 
-void Example() {
+## 返回值
-    XCEngine::Memory::ProxyAllocator object;
+
-    // 根据上下文补齐参数后调用 ProxyAllocator::Allocate(...)。
+- `void*` - 底层分配器返回的指针；失败时通常为 `nullptr`。
-    (void)object;
+
-}
+## 注意事项
-```
+
+- 统计记录的是“请求大小”，不是底层分配器真实消耗的字节数。
+- 如果 `m_underlying == nullptr`，当前实现会直接解引用空指针。
+- 由于 [Free](Free.md) 的释放统计存在缺陷，这里的峰值更新也可能被连带污染。
 
 ## 相关文档
 
-- [返回类总览](ProxyAllocator.md)
+- [返回类型总览](ProxyAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Free](Free.md)
+- [GetStats](GetStats.md)

docs/api/XCEngine/Memory/ProxyAllocator/Constructor.md

@@ -1,30 +1,36 @@
-# ProxyAllocator::ProxyAllocator()
+# ProxyAllocator::Constructor
 
-构造对象。
+构造一个代理分配器。
 
 ```cpp
 ProxyAllocator(IAllocator* underlying, const char* name);
 ```
 
-该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前构造函数只做成员保存：
-- `underlying` - 参数语义详见头文件声明。
-- `name` - 参数语义详见头文件声明。
 
-**返回：** `void` - 无返回值。
+- `m_underlying = underlying`
+- `m_name = name`
 
-**示例：**
+它不会复制名称字符串，也不会接管底层分配器所有权。
 
-```cpp
+## 参数
-#include <XCEngine/Memory/ProxyAllocator.h>
 
-void Example() {
+- `underlying` - 被代理的底层分配器。
-    XCEngine::Memory::ProxyAllocator object;
+- `name` - 代理名称。
-}
+
-```
+## 返回值
+
+- 无。
+
+## 当前实现限制
+
+- 不校验 `underlying` 是否为空。
+- 不复制 `name` 内容，只保存原始指针。
+- 调用方必须保证底层分配器和名称字符串在 `ProxyAllocator` 生命周期内保持有效。
 
 ## 相关文档
 
-- [返回类总览](ProxyAllocator.md)
+- [返回类型总览](ProxyAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetName](GetName.md)

docs/api/XCEngine/Memory/ProxyAllocator/Free.md

@@ -1,31 +1,36 @@
 # ProxyAllocator::Free
 
-公开方法，详见头文件声明。
+通过底层分配器释放内存，并更新代理统计。
 
 ```cpp
 void Free(void* ptr) override;
 ```
 
-该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现会先加锁，然后执行：
-- `ptr` - 参数语义详见头文件声明。
 
-**返回：** `void` - 无返回值。
+1. 调用 `m_underlying->Free(ptr)`。
+2. 执行 `m_stats.totalFreed += m_stats.allocationCount`。
+3. 执行 `m_stats.allocationCount--`。
 
-**示例：**
+## 参数
 
-```cpp
+- `ptr` - 要释放的指针。
-#include <XCEngine/Memory/ProxyAllocator.h>
 
-void Example() {
+## 返回值
-    XCEngine::Memory::ProxyAllocator object;
+
-    // 根据上下文补齐参数后调用 ProxyAllocator::Free(...)。
+- 无。
-    (void)object;
+
-}
+## 当前实现限制
-```
+
+- `totalFreed` 增加的是“当前 allocation count”，不是被释放块的真实字节数。
+- 如果 `allocationCount` 当前为 `0`，执行 `m_stats.allocationCount--` 会发生无符号下溢。
+- `ptr` 是否允许为 `nullptr`，取决于底层分配器；代理层没有额外保护。
+- 如果 `m_underlying == nullptr`，当前实现会直接解引用空指针。
 
 ## 相关文档
 
-- [返回类总览](ProxyAllocator.md)
+- [返回类型总览](ProxyAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Allocate](Allocate.md)
+- [GetTotalFreed](GetTotalFreed.md)

docs/api/XCEngine/Memory/ProxyAllocator/GetAllocationCount.md

@@ -1,30 +1,25 @@
 # ProxyAllocator::GetAllocationCount
 
-获取相关状态或对象。
+查询当前统计中的分配计数。
 
 ```cpp
 size_t GetAllocationCount() const override;
 ```
 
-该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回 `m_stats.allocationCount`。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `size_t` - 代理内部记录的分配计数。
 
-```cpp
+## 注意事项
-#include <XCEngine/Memory/ProxyAllocator.h>
 
-void Example() {
+- 这不是底层分配器的权威状态，而是代理层自己的统计字段。
-    XCEngine::Memory::ProxyAllocator object;
+- 由于 [Free](Free.md) 可能发生下溢、[Reallocate](Reallocate.md) 又不调整统计，这个值不应被当作严格可信的实时分配数。
-    // 根据上下文补齐参数后调用 ProxyAllocator::GetAllocationCount(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](ProxyAllocator.md)
+- [返回类型总览](ProxyAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetStats](GetStats.md)

docs/api/XCEngine/Memory/ProxyAllocator/GetName.md

@@ -1,30 +1,24 @@
 # ProxyAllocator::GetName
 
-获取相关状态或对象。
+查询代理名称。
 
 ```cpp
 const char* GetName() const override;
 ```
 
-该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回 `m_name`。
 
-**返回：** `const char*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `const char*` - 构造时传入的名称指针。
 
-```cpp
+## 注意事项
-#include <XCEngine/Memory/ProxyAllocator.h>
 
-void Example() {
+- 名称字符串不会被复制；如果原始字符串失效，这里返回的就是悬空指针。
-    XCEngine::Memory::ProxyAllocator object;
-    // 根据上下文补齐参数后调用 ProxyAllocator::GetName(...)。
-    (void)object;
-}
-```
 
 ## 相关文档
 
-- [返回类总览](ProxyAllocator.md)
+- [返回类型总览](ProxyAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Constructor](Constructor.md)

docs/api/XCEngine/Memory/ProxyAllocator/GetPeakAllocated.md

@@ -1,30 +1,31 @@
 # ProxyAllocator::GetPeakAllocated
 
-获取相关状态或对象。
+查询峰值净分配量。
 
 ```cpp
 size_t GetPeakAllocated() const override;
 ```
 
-该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回 `m_stats.peakAllocated`。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+这个字段只会在 [Allocate](Allocate.md) 成功时更新，更新依据是：
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/ProxyAllocator.h>
+m_stats.totalAllocated - m_stats.totalFreed
-
-void Example() {
-    XCEngine::Memory::ProxyAllocator object;
-    // 根据上下文补齐参数后调用 ProxyAllocator::GetPeakAllocated(...)。
-    (void)object;
-}
 ```
 
+## 返回值
+
+- `size_t` - 代理层记录的峰值净分配量。
+
+## 注意事项
+
+- 由于 `totalFreed` 的统计当前有缺陷，这里的峰值也可能失真。
+- [Reallocate](Reallocate.md) 不更新统计，因此大缓冲重分配不会反映到峰值里。
+
 ## 相关文档
 
-- [返回类总览](ProxyAllocator.md)
+- [返回类型总览](ProxyAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetTotalAllocated](GetTotalAllocated.md)

docs/api/XCEngine/Memory/ProxyAllocator/GetStats.md

@@ -1,30 +1,34 @@
 # ProxyAllocator::GetStats
 
-获取相关状态或对象。
+读取完整统计结构。
 
 ```cpp
 const Stats& GetStats() const;
 ```
 
-该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现直接返回内部成员 `m_stats` 的常量引用，不会复制数据，也不会在读取时加锁。
 
-**返回：** `const Stats&` - 返回值语义详见头文件声明。
+`Stats` 结构当前包含这些字段：
 
-**示例：**
+- `totalAllocated`
+- `totalFreed`
+- `peakAllocated`
+- `allocationCount`
+- `memoryOverhead`
 
-```cpp
+## 返回值
-#include <XCEngine/Memory/ProxyAllocator.h>
 
-void Example() {
+- `const Stats&` - 指向内部统计结构的只读引用。
-    XCEngine::Memory::ProxyAllocator object;
+
-    // 根据上下文补齐参数后调用 ProxyAllocator::GetStats(...)。
+## 注意事项
-    (void)object;
+
-}
+- 这是对内部状态的直接暴露，不适合在并发写入期间无保护读取。
-```
+- `memoryOverhead` 字段当前始终保持默认值 `0`。
+- `totalFreed` 和由它推导出的字段目前不完全准确。
 
 ## 相关文档
 
-- [返回类总览](ProxyAllocator.md)
+- [返回类型总览](ProxyAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetAllocationCount](GetAllocationCount.md)

docs/api/XCEngine/Memory/ProxyAllocator/GetTotalAllocated.md

@@ -1,30 +1,27 @@
 # ProxyAllocator::GetTotalAllocated
 
-获取相关状态或对象。
+查询累计分配字节数。
 
 ```cpp
 size_t GetTotalAllocated() const override;
 ```
 
-该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回 `m_stats.totalAllocated`。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+这个字段在 [Allocate](Allocate.md) 成功时按“请求大小”累加，不会向底层分配器反查真实消耗。
 
-**示例：**
+## 返回值
 
-```cpp
+- `size_t` - 代理层记录的累计请求字节数。
-#include <XCEngine/Memory/ProxyAllocator.h>
 
-void Example() {
+## 注意事项
-    XCEngine::Memory::ProxyAllocator object;
+
-    // 根据上下文补齐参数后调用 ProxyAllocator::GetTotalAllocated(...)。
+- 这不是底层分配器的精确字节记账。
-    (void)object;
+- 当前读取路径没有加锁，更适合在受控快照点使用。
-}
-```
 
 ## 相关文档
 
-- [返回类总览](ProxyAllocator.md)
+- [返回类型总览](ProxyAllocator.md)
-- [返回模块目录](../Memory.md)
+- [GetTotalFreed](GetTotalFreed.md)

docs/api/XCEngine/Memory/ProxyAllocator/GetTotalFreed.md

@@ -1,30 +1,27 @@
 # ProxyAllocator::GetTotalFreed
 
-获取相关状态或对象。
+查询累计释放字节数。
 
 ```cpp
 size_t GetTotalFreed() const override;
 ```
 
-该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回 `m_stats.totalFreed`。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+但这个字段的写入逻辑有明显缺陷：[Free](Free.md) 并不是按被释放块大小累加，而是把“调用当时的 allocation count”加进来。
 
-**示例：**
+## 返回值
 
-```cpp
+- `size_t` - 代理层当前记录的释放统计值。
-#include <XCEngine/Memory/ProxyAllocator.h>
 
-void Example() {
+## 注意事项
-    XCEngine::Memory::ProxyAllocator object;
+
-    // 根据上下文补齐参数后调用 ProxyAllocator::GetTotalFreed(...)。
+- 这个值当前不代表真实释放字节数。
-    (void)object;
+- 基于它计算的净分配量和峰值也会受影响。
-}
-```
 
 ## 相关文档
 
-- [返回类总览](ProxyAllocator.md)
+- [返回类型总览](ProxyAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Free](Free.md)

docs/api/XCEngine/Memory/ProxyAllocator/ProxyAllocator.md

@@ -6,34 +6,54 @@
 
 **头文件**: `XCEngine/Memory/ProxyAllocator.h`
 
-**描述**: 定义 `XCEngine/Memory` 子目录中的 `ProxyAllocator` public API。
+**描述**: 在已有分配器外面包一层统计逻辑的代理分配器。
 
 ## 概述
 
-`ProxyAllocator.h` 是 `XCEngine/Memory` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`ProxyAllocator` 不直接拥有原始堆，而是把所有内存操作转发给底层分配器，并在外层记录统计信息。这种设计适合：
 
-## 声明概览
+- 调试某个子系统的内存使用
+- 给同一个底层分配器增加具名统计视图
+- 在不改底层分配器实现的前提下，追加追踪逻辑
 
-| 声明 | 类型 | 说明 |
+## 所有权
-|------|------|------|
-| `ProxyAllocator` | `class` | 继承自 `IAllocator` 的公开声明。 |
 
-## 公共方法
+- [Constructor](Constructor.md) 接收一个底层 `IAllocator*` 和一个名称。
+- 当前 `ProxyAllocator` 不拥有底层分配器，不会在销毁时释放它。
+- 当前实现既不校验底层分配器是否为空，也不复制名称字符串。
+- `MemoryManager::CreateProxyAllocator` 当前总是包装系统分配器，而不是任意自定义底层分配器。
 
-| 方法 | 描述 |
+## 当前实现限制
+
+- [Free](Free.md) 会把 `totalFreed` 增加为“当前 allocation count”，而不是被释放块的真实大小，因此释放字节统计当前并不准确。
+- [Reallocate](Reallocate.md) 只转发调用，不更新统计信息。
+- 如果底层分配器失效或被提前销毁，后续所有代理操作都可能触发未定义行为。
+- `GetStats()` 返回内部结构体引用，当前没有为只读访问额外加锁。
+- `memoryOverhead` 字段存在，但当前没有被维护。
+
+## 线程语义
+
+- `Allocate`、`Free` 和 `Reallocate` 当前在内部使用 `Threading::Mutex` 保护统计更新。
+- `GetStats()` 是无锁只读返回；更适合在无并发修改或调试快照场景下读取。
+
+## 公开方法
+
+| 方法 | 说明 |
 |------|------|
-| [ProxyAllocator()](Constructor.md) | 构造对象。 |
+| [Constructor](Constructor.md) | 构造代理分配器。 |
-| [Allocate](Allocate.md) | 公开方法，详见头文件声明。 |
+| [Allocate](Allocate.md) | 通过底层分配器分配，并更新统计。 |
-| [Free](Free.md) | 公开方法，详见头文件声明。 |
+| [Free](Free.md) | 通过底层分配器释放，并更新统计。 |
-| [Reallocate](Reallocate.md) | 公开方法，详见头文件声明。 |
+| [Reallocate](Reallocate.md) | 转发重分配。 |
-| [GetTotalAllocated](GetTotalAllocated.md) | 获取相关状态或对象。 |
+| [GetTotalAllocated](GetTotalAllocated.md) | 查询累计分配字节。 |
-| [GetTotalFreed](GetTotalFreed.md) | 获取相关状态或对象。 |
+| [GetTotalFreed](GetTotalFreed.md) | 查询累计释放字节。 |
-| [GetPeakAllocated](GetPeakAllocated.md) | 获取相关状态或对象。 |
+| [GetPeakAllocated](GetPeakAllocated.md) | 查询峰值净分配量。 |
-| [GetAllocationCount](GetAllocationCount.md) | 获取相关状态或对象。 |
+| [GetAllocationCount](GetAllocationCount.md) | 查询当前统计中的分配计数。 |
-| [GetStats](GetStats.md) | 获取相关状态或对象。 |
+| [GetStats](GetStats.md) | 读取完整统计结构。 |
-| [GetName](GetName.md) | 获取相关状态或对象。 |
+| [GetName](GetName.md) | 查询代理名称。 |
 
 ## 相关文档
 
-- [当前目录](../Memory.md) - 返回 `Memory` 平行目录
+- [当前模块](../Memory.md)
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [IAllocator](../Allocator/Allocator.md)
+- [MemoryManager](../MemoryManager/MemoryManager.md)
+- [Allocator Selection And Current Limits](../../../_guides/Memory/Allocator-Selection-And-Current-Limits.md)

docs/api/XCEngine/Memory/ProxyAllocator/Reallocate.md

@@ -1,32 +1,35 @@
 # ProxyAllocator::Reallocate
 
-公开方法，详见头文件声明。
+通过底层分配器重分配内存。
 
 ```cpp
 void* Reallocate(void* ptr, size_t newSize) override;
 ```
 
-该方法声明于 `XCEngine/Memory/ProxyAllocator.h`，当前页面用于固定 `ProxyAllocator` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
+当前实现会先加锁，然后仅做一件事：
-- `ptr` - 参数语义详见头文件声明。
-- `newSize` - 参数语义详见头文件声明。
-
-**返回：** `void*` - 返回值语义详见头文件声明。
-
-**示例：**
 
 ```cpp
-#include <XCEngine/Memory/ProxyAllocator.h>
+return m_underlying->Reallocate(ptr, newSize);
-
-void Example() {
-    XCEngine::Memory::ProxyAllocator object;
-    // 根据上下文补齐参数后调用 ProxyAllocator::Reallocate(...)。
-    (void)object;
-}
 ```
 
+## 参数
+
+- `ptr` - 原指针。
+- `newSize` - 新大小。
+
+## 返回值
+
+- `void*` - 底层分配器返回的新指针。
+
+## 当前实现限制
+
+- 不更新 `totalAllocated`、`totalFreed`、`peakAllocated` 或 `allocationCount`。
+- 如果底层分配器会移动内存，这里的返回值可能与 `ptr` 不同。
+- 如果 `m_underlying == nullptr`，当前实现会直接解引用空指针。
+
 ## 相关文档
 
-- [返回类总览](ProxyAllocator.md)
+- [返回类型总览](ProxyAllocator.md)
-- [返回模块目录](../Memory.md)
+- [Allocate](Allocate.md)

docs/api/_guides/Memory/Allocator-Selection-And-Current-Limits.md

@@ -0,0 +1,124 @@
+# Allocator Selection And Current Limits
+
+## 为什么引擎要有多种分配器
+
+商业级引擎不会把所有内存都交给一套通用堆分配器。原因很现实：
+
+- 帧级临时数据的生命周期极短，逐块释放反而是额外成本。
+- 大量固定尺寸对象如果走通用堆，碎片和元数据开销通常不划算。
+- 调试阶段又往往需要单独统计某个系统到底分了多少内存。
+
+这就是 `XCEngine::Memory` 当前这组 API 的设计出发点。
+
+## 现在这几个分配器分别适合什么
+
+### `LinearAllocator`
+
+适合：
+
+- 一整批数据统一释放
+- 帧级或阶段级临时内存
+- 极低开销的顺序分配
+
+不适合：
+
+- 需要单个对象独立释放
+- 需要通用 `realloc`
+
+如果你熟悉 Unity 或其它引擎，可以把它理解为更接近 arena / frame allocator 这一类思路，而不是常驻对象堆。
+
+### `PoolAllocator`
+
+适合：
+
+- 固定尺寸或尺寸上界稳定的对象
+- 高频分配 / 释放
+- 想避免通用堆碎片
+
+不适合：
+
+- 大小变化大的对象
+- 需要可变尺寸重分配
+
+### `ProxyAllocator`
+
+适合：
+
+- 给现有分配器加统计视图
+- 调试某个系统的内存用量
+- 不想修改底层分配器实现，但想额外记录指标
+
+不适合：
+
+- 被当作完整可信的内存分析器
+
+## 当前版本最需要诚实面对的事
+
+这套模块已经有了不错的 API 形状，但实现还没有完全跟上。
+
+最重要的限制有这些：
+
+- `LinearAllocator::Free` 和 `Reallocate` 还没有完成。
+- `PoolAllocator::Reallocate` 还没有完成。
+- `ProxyAllocator` 的释放统计当前不准确。
+- `MemoryManager` 的泄漏和报表接口现在只是占位输出。
+- 部分统计方法名字很强，但当前返回值更接近“固定上界”而不是真实历史峰值。
+- 通过 `MemoryManager` 创建且依赖系统分配器的对象，目前仍要求调用方在 `Shutdown()` 之前主动销毁。
+
+这意味着当前更合理的使用方式是：
+
+- 把这些分配器当作明确生命周期的工具型组件；
+- 不要把它们当成已经完备的内存诊断平台。
+
+## 如何选择
+
+如果你只是要一块批量临时内存：
+
+```cpp
+auto allocator = XCEngine::Memory::MemoryManager::Get().CreateLinearAllocator(1024 * 1024);
+```
+
+如果你要大量固定尺寸对象：
+
+```cpp
+auto allocator = XCEngine::Memory::MemoryManager::Get().CreatePoolAllocator(sizeof(MyNode), 1024);
+```
+
+如果你要统计某个系统的分配情况：
+
+```cpp
+auto allocator = XCEngine::Memory::MemoryManager::Get().CreateProxyAllocator("RenderGraph");
+```
+
+这里还要额外记住一点：
+
+- `CreateProxyAllocator()` 应在 `Initialize()` 之后调用。
+- `CreateLinearAllocator()` 如果绑定了系统分配器作为父分配器，也应在 `Shutdown()` 前完成销毁。
+
+## 为什么要保留 `IAllocator`
+
+`IAllocator` 的价值不在“虚函数本身”，而在于它允许上层容器和子系统表达“我需要一个分配策略”，而不是“我必须依赖某个具体实现”。
+
+这和很多商业引擎里的思路一致：
+
+- 容器依赖 allocator 接口
+- 上层根据数据生命周期决定用哪种分配器
+- 调试阶段可以额外套 tracking / proxy 层
+
+## 当前阶段最值得补的方向
+
+如果继续把这个模块做实，最值得优先补的通常是：
+
+1. 给 `LinearAllocator` 和 `PoolAllocator` 明确补完 `Reallocate` / 回收语义，或者在 API 层彻底禁掉不支持的操作。
+2. 修正 `ProxyAllocator` 的统计口径。
+3. 让 `MemoryManager` 的泄漏与报表接口真正产出结构化结果。
+4. 为不同分配器补充更严格的越界、重复释放和对齐校验。
+
+## 相关 API
+
+- [Memory](../../XCEngine/Memory/Memory.md)
+- [IAllocator](../../XCEngine/Memory/Allocator/Allocator.md)
+- [LinearAllocator](../../XCEngine/Memory/LinearAllocator/LinearAllocator.md)
+- [PoolAllocator](../../XCEngine/Memory/PoolAllocator/PoolAllocator.md)
+- [ProxyAllocator](../../XCEngine/Memory/ProxyAllocator/ProxyAllocator.md)
+- [MemoryManager](../../XCEngine/Memory/MemoryManager/MemoryManager.md)

docs/api/_meta/rebuild-status.md

@@ -1,12 +1,12 @@
 # API 文档重构状态
 
-**生成时间**: `2026-03-26 17:39:11`
+**生成时间**: `2026-03-26 18:01:19`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`
 
 ## 摘要
 
-- Markdown 页面数（全部）: `2443`
+- Markdown 页面数（全部）: `2444`
 - Markdown 页面数（canonical）: `2436`
 - Public headers 数: `185`
 - 有效头文件引用数（全部）: `185`