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. 继续清理旧树里的历史空目录、重复入口和剩余结构噪音。