XCEngine/docs/plan/API文档目录重构计划_2026-04-09.md

# API文档目录重构计划

## 1. 背景

当前 API 文档树已经出现明显的“双主线错位”：

- `docs/api/XCEngine/Editor/**` 主要对应旧 `editor/src/**` 的 ImGui 编辑器应用层。
- `new_editor/include/XCEditor/**` 与 `new_editor/src/**` 已经形成新的 Editor 基础层主线。
- 这条主线最初没有进入当前 canonical API 树，审计脚本也一度没有覆盖 `new_editor/include/XCEditor/**`。

这意味着继续只在 `docs/api/XCEngine/Editor/**` 上增量修补，会越来越偏离真实代码结构。

## 1.1 2026-04-10 状态更新

截至 `2026-04-10 17:07:09`，以下阶段已经落地：

- `docs/api/XCEditor/**` 已建立并进入 canonical 根树
- 审计脚本已经覆盖：
  - `engine/include/XCEngine/**`
  - `new_editor/include/XCEditor/**`
  - `editor/src/**`
- `docs/api/main.md` 已建立 `XCEngine + XCEditor` 双根入口
- `XCUIDemoPanel` 已退出当前 canonical API 树
- `Resources/Model` 与 `Resources/GaussianSplat` 已补齐 canonical 入口

因此这份计划里“为什么要拆出 `XCEditor` 根树”的判断仍然有效，但 `Phase B / C` 不再是未来动作，而是已完成事实。

## 2. 当前判断

### 2.1 旧 `Editor` 文档树继续保留，但必须收紧边界

- `docs/api/XCEngine/Editor/**` 继续只文档化旧 `editor/src/**`。
- 不再把它当成未来 Editor 主线 API 树。
- 其中 `Application / EditorResources / Theme / XCUIBackend / panels / Viewport` 等内容，明确视为旧编辑器应用层。

### 2.2 新主线已拆出独立文档树

当前已新增：

- `docs/api/XCEditor/`

首层目录直接镜像 `new_editor/include/XCEditor/**`：

- `Collections`
- `Fields`
- `Foundation`
- `Shell`
- `Widgets`

这样做的原因很直接：

- 与真实 include 路径一致，后续自动审计最容易做。
- 不会把新主线继续混进旧 `XCEngine/Editor` 树里。
- 可以允许页面里的命名空间继续写真实值 `XCEngine::UI::Editor` / `XCEngine::UI::Editor::Widgets`，而目录只负责和头文件路径对齐。

### 2.3 新旧两棵树的职责应明确分开

- `docs/api/XCEngine/Editor/**`
  - 旧编辑器应用层、宿主层、过渡层、当前产品参考实现。
- `docs/api/XCEditor/**`
  - `new_editor` 的新 Editor 基础层与宿主骨架。

## 3. 已确认的结构漂移

### 3.1 文档树覆盖不到 `new_editor/include/XCEditor`

当前新主线 public headers 已经至少包含：

- `XCEditor/Collections/*`
- `XCEditor/Fields/*`
- `XCEditor/Foundation/*`
- `XCEditor/Shell/*`
- `XCEditor/Widgets/*`

现在 `docs/api` 里已经有对应的 `XCEditor` 根树。

### 3.2 旧树中仍混有已经过时的过渡页

当前这类问题已经完成清理，最典型的是：

- `docs/api/XCEngine/Editor/panels/XCUIDemoPanel/XCUIDemoPanel.md`
  - 仍引用已不存在的 `editor/src/panels/XCUIDemoPanel.h`

这类页面已经从 active canonical 树移除，不再继续假设旧源码路径仍成立。

### 3.3 审计工具口径落后

当前这项问题已经收口；审计脚本现在已经把：

- `new_editor/include/XCEditor/**/*.h`

纳入 canonical 统计，`XCEditor` 缺页会直接出现在审计结果里。

## 4. 分阶段执行

## Phase A：收紧旧树边界

- 在 `docs/api/XCEngine/Editor/Editor.md` 明确“这里只对应旧 `editor/src/**`”。
- 修掉旧树里已经失效的 source refs。
- 继续补齐旧 `editor/src/**` 当前缺失的 canonical 页，避免现有审计长期失真。

## Phase B：建立 `XCEditor` 新根树（已完成）

- 新建 `docs/api/XCEditor/XCEditor.md`
- 新建 5 个首层 overview：
  - `Collections`
  - `Fields`
  - `Foundation`
  - `Shell`
  - `Widgets`
- 建立 `docs/api/main.md` 到新根树的入口链接

## Phase C：接入新审计口径（已完成）

- 扩展审计脚本识别 `new_editor/include/XCEditor/**/*.h`
- 统计 `docs/api/XCEditor/**` 的 canonical 覆盖率
- 区分：
  - 旧 `editor/src/**` 应用层源码页
  - 新 `XCEditor/**` public header 页

## Phase D：按新主线分批补页（进行中）

推荐顺序：

1. `Foundation`
2. `Widgets`
3. `Collections`
4. `Fields`
5. `Shell`

原因：

- `Foundation` 与 `Widgets` 是多数页面的前置语义。
- `Collections` / `Fields` 数量多，但结构相对规整，适合并行。
- `Shell` 依赖最多，最好放后面统一写。

## Phase E：旧树去历史包袱（进行中）

- 删除或改写已经脱离旧源码的过渡页
- 把“旧 editor 参考实现”和“new_editor 正式主线”在相关 overview 中互相链接，但不再混放
- 避免后续继续把 `new_editor` 内容塞进 `docs/api/XCEngine/Editor/**`

## 5. 本轮执行口径

当前后续重点已经转到：

1. 继续回归高风险 `RHI / Rendering / Editor/Viewport` 内容页，避免源码继续演进后文档再次漂移。
2. 继续清理旧树里的历史空目录、重复入口和剩余结构噪音。