docs: rebuild Memory API content

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