docs: rebuild Scene API content

docs/api/XCEngine/Scene/SceneManager/SetActiveScene.md

@@ -1,44 +1,36 @@
 # SceneManager::SetActiveScene
 
-设置相关状态或配置。
-
-该方法在 `XCEngine/Scene/SceneManager.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
+设置活动场景。
 
 ```cpp
 void SetActiveScene(Scene* scene);
-```
-
-**参数：**
-- `scene` - 参数语义详见头文件声明。
-
-**返回：** `void` - 无返回值。
-
-## 重载 2: 声明
-
-```cpp
 void SetActiveScene(const std::string& sceneName);
 ```
 
-**参数：**
-- `sceneName` - 参数语义详见头文件声明。
+## 行为说明
 
-**返回：** `void` - 无返回值。
+当前有两个重载：
 
-**示例：**
+- 指针重载会在 `m_activeScene != scene` 时直接写入 `m_activeScene = scene`，然后触发 [OnActiveSceneChanged](OnActiveSceneChanged.md)。
+- 字符串重载会先在 `m_scenes` 中查找 key，找到后再调用指针重载。
 
-```cpp
-#include <XCEngine/Scene/SceneManager.h>
+## 参数
 
-void Example() {
-    XCEngine::Components::SceneManager object;
-    // 根据上下文补齐参数后调用 SceneManager::SetActiveScene(...)。
-    (void)object;
-}
-```
+- `scene` - 目标活动场景指针。
+- `sceneName` - 目标场景 key。
+
+## 返回值
+
+- 无。
+
+## 当前实现限制
+
+- 指针重载不会校验 `scene` 是否真的来自 `SceneManager` 当前持有的场景集合。
+- 当前不会同步 `Scene::SetActive()`。
+- 如果传入的指针就是当前活动场景，不会触发事件。
+- 传入 `nullptr` 时，如果当前活动场景非空，会把活动场景清空并触发切换事件。
 
 ## 相关文档
 
-- [返回类总览](SceneManager.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](SceneManager.md)
+- [GetActiveScene](GetActiveScene.md)