docs: expand gameobject helper docs

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

@@ -1,45 +1,47 @@
 # GameObject::SetParent
 
-设置相关状态或配置。
+修改对象的父节点，并同步场景根列表、`Transform` 层级与激活态传播。
 
-该方法在 `XCEngine/Components/GameObject.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
+该方法当前提供两个公开重载：
 
 ```cpp
 void SetParent(GameObject* parent);
-```
-
-**参数：**
-- `parent` - 参数语义详见头文件声明。
-
-**返回：** `void` - 无返回值。
-
-## 重载 2: 声明
-
-```cpp
 void SetParent(GameObject* parent, bool worldPositionStays);
 ```
 
-**参数：**
-- `parent` - 参数语义详见头文件声明。
-- `worldPositionStays` - 参数语义详见头文件声明。
+## 重载关系
 
-**返回：** `void` - 无返回值。
+- `SetParent(parent)` 当前等价于 `SetParent(parent, true)`
+- `worldPositionStays` 会继续传给 `TransformComponent::SetParent(...)`
 
-**示例：**
+## 行为说明
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+当前实现会处理以下事情：
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::SetParent(...)。
-    (void)object;
-}
-```
+- 若目标父节点与当前父节点相同，直接返回
+- 若 `parent == this`，直接返回
+- 从旧父节点子列表或场景根列表中移除当前对象
+- 更新 `m_parent`
+- 加入新父节点的子列表，或重新进入场景根列表
+- 调用 `GetTransform()->SetParent(...)`
+- 如有需要，重新传播 `active in hierarchy` 变化
+
+## 参数
+
+- `parent` - 新父对象；传 `nullptr` 表示把对象变成根对象。
+- `worldPositionStays` - 是否尽量保持当前世界空间变换。
+
+## 返回值
+
+- 无。
+
+## 设计提示
+
+把“对象层级”和“Transform 层级”同时更新，是商业引擎对象系统的必要一致性要求。否则编辑器看到的对象树和运行时空间层级会很容易脱节。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GameObject](GameObject.md)
+- [GetParent](GetParent.md)
+- [DetachFromParent](DetachFromParent.md)
+- [SetActive](SetActive.md)