docs: expand gameobject helper docs

docs/api/XCEngine/Components/GameObject/DetachChildren.md

@@ -1,30 +1,33 @@
 # GameObject::DetachChildren
 
-公开方法，详见头文件声明。
+把当前对象的所有直接子对象全部分离出去，并保持它们的世界空间变换。
 
 ```cpp
 void DetachChildren();
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
-
-**返回：** `void` - 无返回值。
-
-**示例：**
+当前实现会先复制一份 `m_children`，然后对副本中的每个子对象调用：
 
 ```cpp
-#include <XCEngine/Components/GameObject.h>
-
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::DetachChildren(...)。
-    (void)object;
-}
+child->SetParent(nullptr, true);
 ```
 
+这么做的目的，是避免在遍历过程中直接修改原始 `m_children` 容器导致迭代失效。
+
+## 结果语义
+
+调用完成后：
+
+- 当前对象的直接子列表会被清空
+- 每个原子对象都会变成根对象，或在无场景时变成无父独立对象
+- 每个子对象都会尽量保持原世界空间变换
+
+`tests/Components/test_game_object.cpp` 中的 `DetachChildren` 已验证父对象的 `GetChildCount()` 会从原值变成 `0`。
+
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [DetachFromParent](DetachFromParent.md)
+- [SetParent](SetParent.md)
+- [GetChildren](GetChildren.md)