docs: rebuild Memory API content

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
-#include <XCEngine/Memory/PoolAllocator.h>
+- `ptr` - 要归还的 block 指针。
 
-void Example() {
-    XCEngine::Memory::PoolAllocator object;
-    // 根据上下文补齐参数后调用 PoolAllocator::Free(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- 无。
+
+## 当前实现限制
+
+- 不验证 `ptr` 是否真的来自当前池。
+- 不验证 `ptr` 是否位于 block 边界。
+- 不防止重复释放。
+- 如果把不属于当前池的地址传进来，可能破坏空闲链表甚至直接写坏任意内存。
+- 如果重复释放同一块，`m_freeBlocks` 可能大于 `m_totalBlocks`，随后统计接口会失真甚至发生无符号下溢。
 
 ## 相关文档
 
-- [返回类总览](PoolAllocator.md)
-- [返回模块目录](../Memory.md)
+- [返回类型总览](PoolAllocator.md)
+- [Allocate](Allocate.md)
+- [Contains](Contains.md)