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 树。
• 现有审计脚本只覆盖 engine/include/XCEngine/** 与 editor/src/**，没有覆盖 new_editor/include/XCEditor/**。

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

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

这类页面需要单独清理，不能继续假设旧源码路径仍成立。

3.3 审计工具口径落后

当前 docs/api/_tools/audit_api_docs.py 的覆盖口径没有把：

• new_editor/include/XCEditor/**/*.h

纳入 canonical 统计，所以即使新主线完全缺文档，审计也不会报警。

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. 先把现有审计缺口补齐，保证旧树不继续烂下去。
2. 同时开始落 XCEditor 文档树重构计划和入口边界说明，为下一轮结构迁移做准备。