docs: Fix memory module documentation discrepancies

- Add missing PoolAllocator class overview with methods table
- Add missing LinearAllocator class overview with methods table
- Add missing ProxyAllocator class overview with methods table
- Fix PoolAllocator::Allocate example code and comments
- Clarify ProxyAllocator::Free totalFreed calculation behavior
- Fix CreateLinearAllocator complexity from O(size) to O(1)
- Add note about Reallocate thread safety in ProxyAllocator

docs/api/memory/linear-allocator/linear-allocator.md

@@ -1,7 +1,52 @@
-# LinearAllocator::LinearAllocator
+# LinearAllocator
+
+**命名空间**: `XCEngine::Memory`
+
+**类型**: `class`
+
+**描述**: 线性分配器，适合帧分配和临时对象。
+
+## 概述
+
+`LinearAllocator` 是一种顺序分配器，预分配一个大缓冲区，每次分配从缓冲区起始位置顺序分配，偏移量递增。它不适合需要释放任意块的场景，但分配和清除非常高效，常用于帧分配器。
+
+## 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `LinearAllocator` | 构造线性分配器 |
+| `~LinearAllocator` | 析构函数，释放底层缓冲区 |
+
+### 内存操作
+
+| 方法 | 描述 |
+|------|------|
+| `Allocate` | 顺序分配内存 |
+| `Free` | 无效果（不支持） |
+| `Reallocate` | 不支持（始终返回 nullptr） |
+| `Clear` | 清空所有分配 |
+
+### 标记和回滚
+
+| 方法 | 描述 |
+|------|------|
+| `GetMarker` | 获取当前位置标记 |
+| `SetMarker` | 回滚到指定标记位置 |
+
+### 查询方法
+
+| 方法 | 描述 |
+|------|------|
+| `GetUsedSize` | 获取已使用字节数 |
+| `GetCapacity` | 获取总容量 |
+
+## 构造函数
 
 ```cpp
 explicit LinearAllocator(size_t size, IAllocator* parent = nullptr);
+~LinearAllocator() override;
 ```
 
 构造一个线性分配器，预分配指定大小的缓冲区。如果提供了 `parent` 分配器，则使用它分配底层缓冲区；否则使用系统默认分配（`_aligned_malloc`，8 字节对齐）。
@@ -14,6 +59,8 @@ explicit LinearAllocator(size_t size, IAllocator* parent = nullptr);
 
 **复杂度：** O(n)，需要分配 `size` 大小的缓冲区
 
+**注意：** `Free` 和 `Reallocate` 方法无实际效果。`Free` 是空操作，`Reallocate` 始终返回 `nullptr`。
+
 **示例：**
 
 ```cpp
@@ -32,4 +79,5 @@ void* ptr = allocator1.Allocate(256);
 
 ## 相关文档
 
-- [LinearAllocator 总览](linear-allocator.md) - 返回类总览
+- [Memory 模块总览](../memory.md) - 返回模块总览
+- [IAllocator](../allocator/allocator.md) - 分配器接口

docs/api/memory/manager/create-linear-allocator.md

@@ -11,7 +11,7 @@ std::unique_ptr<LinearAllocator> CreateLinearAllocator(size_t size);
 
 **返回：** LinearAllocator 的 unique_ptr
 
-**复杂度：** O(size)
+**复杂度：** O(1)
 
 **示例：**
 

docs/api/memory/manager/create-pool-allocator.md

@@ -12,7 +12,7 @@ std::unique_ptr<PoolAllocator> CreatePoolAllocator(size_t blockSize, size_t coun
 
 **返回：** PoolAllocator 的 unique_ptr
 
-**复杂度：** O(blockSize * count)
+**复杂度：** O(blockSize * count)（需要预分配所有块）
 
 **示例：**
 

docs/api/memory/pool-allocator/allocate.md

@@ -19,11 +19,12 @@ void* Allocate(size_t size, size_t alignment = 0) override;
 ```cpp
 #include <XCEngine/Memory/PoolAllocator.h>
 
-PoolAllocator pool(sizeof(int) * 100, 50, alignof(int));
+// 创建能容纳 1000 个整数的内存池
+PoolAllocator pool(sizeof(int), 1000, alignof(int));
 
-// 分配（忽略 size 参数）
-void* block1 = pool.Allocate(1);     // 分配 1 字节
-void* block2 = pool.Allocate(10000); // 也分配一块
+// 分配（忽略 size 参数，只分配固定大小的块）
+void* block1 = pool.Allocate(1);     // 分配一块（实际大小为 sizeof(int)）
+void* block2 = pool.Allocate(10000); // 也分配一块（实际大小为 sizeof(int)）
 
 if (block1 && block2) {
     // 使用分配的内存块

docs/api/memory/pool-allocator/pool-allocator.md

@@ -1,4 +1,42 @@
-# PoolAllocator::PoolAllocator / ~PoolAllocator
+# PoolAllocator
+
+**命名空间**: `XCEngine::Memory`
+
+**类型**: `class`
+
+**描述**: 内存池分配器，预分配固定大小的内存块池。
+
+## 概述
+
+`PoolAllocator` 是一种高效固定块分配器，适合需要频繁分配和释放相同大小对象的场景，如对象池、粒子系统等。它预分配 `poolSize` 个大小为 `blockSize` 字节的内存块，通过空闲链表管理分配和回收。
+
+## 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `PoolAllocator` | 构造内存池分配器 |
+| `~PoolAllocator` | 析构函数，释放整个内存池 |
+
+### 内存操作
+
+| 方法 | 描述 |
+|------|------|
+| `Allocate` | 分配一个内存块 |
+| `Free` | 释放内存块回空闲链表 |
+| `Reallocate` | 不支持（始终返回 nullptr） |
+
+### 查询方法
+
+| 方法 | 描述 |
+|------|------|
+| `Contains` | 检查指针是否属于此池 |
+| `GetBlockSize` | 获取块大小 |
+| `GetFreeBlockCount` | 获取空闲块数量 |
+| `GetTotalBlockCount` | 获取总块数 |
+
+## 构造函数
 
 ```cpp
 PoolAllocator(size_t blockSize, size_t poolSize, size_t alignment = 8);
@@ -16,6 +54,8 @@ PoolAllocator(size_t blockSize, size_t poolSize, size_t alignment = 8);
 
 **复杂度：** O(n)，需要预分配所有块
 
+**注意：** `Reallocate` 方法始终返回 `nullptr`，此分配器不支持重新分配。
+
 **示例：**
 
 ```cpp
@@ -41,4 +81,5 @@ pool.Free(block);
 
 ## 相关文档
 
-- [PoolAllocator 总览](pool-allocator.md) - 返回类总览
+- [Memory 模块总览](../memory.md) - 返回模块总览
+- [IAllocator](../allocator/allocator.md) - 分配器接口

docs/api/memory/proxy-allocator/free.md

@@ -4,7 +4,9 @@
 void Free(void* ptr) override;
 ```
 
-释放内存并记录统计。调用转发到底层分配器，同时更新统计信息：递增 `totalFreed`（累加当前分配计数），并递减 `allocationCount`。由于 ProxyAllocator 不记录单独释放的字节数，`totalFreed` 累加的是 `allocationCount` 而非实际字节大小。
+释放内存并记录统计。调用转发到底层分配器，同时更新统计信息：递增 `totalFreed`（累加当前 `allocationCount`），并递减 `allocationCount`。
+
+**注意：** `totalFreed` 累加的是每次释放时的 `allocationCount`（分配计数）而非实际字节大小。这是一个简化的实现，用于追踪释放操作次数。
 
 **参数：**
 - `ptr` - 指向要释放的内存块

docs/api/memory/proxy-allocator/proxy-allocator.md

@@ -1,4 +1,38 @@
-# ProxyAllocator::ProxyAllocator
+# ProxyAllocator
+
+**命名空间**: `XCEngine::Memory`
+
+**类型**: `class`
+
+**描述**: 代理分配器，用于统计和跟踪底层分配器的分配情况。
+
+## 概述
+
+`ProxyAllocator` 包装一个底层分配器，转发所有分配请求，同时记录详细的统计信息。它线程安全（使用互斥锁保护统计数据），适合需要监控内存使用的场景。
+
+## 公共方法
+
+### 生命周期
+
+| 方法 | 描述 |
+|------|------|
+| `ProxyAllocator` | 构造代理分配器 |
+
+### 内存操作
+
+| 方法 | 描述 |
+|------|------|
+| `Allocate` | 分配内存并记录统计 |
+| `Free` | 释放内存并记录统计 |
+| `Reallocate` | 转发到底层分配器 |
+
+### 统计查询
+
+| 方法 | 描述 |
+|------|------|
+| `GetStats` | 获取详细统计信息 |
+
+## 构造函数
 
 ```cpp
 ProxyAllocator(IAllocator* underlying, const char* name);
@@ -33,4 +67,6 @@ proxy.Free(ptr);
 
 ## 相关文档
 
-- [ProxyAllocator 总览](proxy-allocator.md) - 返回类总览
+- [Memory 模块总览](../memory.md) - 返回模块总览
+- [IAllocator](../allocator/allocator.md) - 分配器接口
+- [MemoryManager](../manager/manager.md) - 内存管理器

docs/api/memory/proxy-allocator/reallocate.md

@@ -4,7 +4,7 @@
 void* Reallocate(void* ptr, size_t newSize) override;
 ```
 
-重新分配内存。调用直接转发到底层分配器，不记录任何统计信息（简化实现）。此方法仅将调用转发给底层分配器。
+重新分配内存。调用转发到底层分配器，不记录额外统计信息（底层分配器的返回值直接返回）。此方法线程安全，内部使用互斥锁保护。
 
 **参数：**
 - `ptr` - 现有内存块指针