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