xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
XCEngine/docs/plan/API文档目录结构第二轮重构计划_2026-04-09.md

7.9 KiB
Raw Permalink Blame History

API 文档目录结构第二轮重构计划

1. 背景

项目最近又经历了一轮较大的源码重构，docs/api/XCEngine 当前虽然顶层大类仍然存在，但内部已经出现了两类更严重的问题：

  • 目录层级错位：文档页名字还对，但挂在了错误的父目录下。
  • 新旧结构并存：旧位置和新位置同时保留，导致同一 API 在文档树里出现两套入口。

这轮重构不再是简单补页，而是要把 docs/api 再次拉回到“与实际源码模块结构平行”的状态。

2. 本轮核对基准

本轮计划基于以下真实代码树做对照：

  • 运行时 public headers：engine/include/XCEngine/**
  • 旧版编辑器 source-backed API：editor/src/**
  • 当前文档树：docs/api/XCEngine/**

同时参考了最新本地审计结果：

  • python -B docs/api/_tools/audit_api_docs.py

2.1 2026-04-10 状态更新

截至 2026-04-10 17:07:09，这份计划里最核心的阶段性目标已经完成：

  • XCUIDemoPanel 已从 canonical 树移除，相关活跃反向链接已清理
  • Rendering 旧错位目录与 stale-token 路径已完成一轮归位/回归
  • Volume / Selection / UI helper / Editor helper 缺页已补齐
  • docs/api/XCEditor/**、Resources/Model/**、Resources/GaussianSplat/** 已进入 canonical 树
  • 审计当前全绿：
    • Invalid header refs = 0
    • Invalid source refs = 0
    • Broken .md links = 0
    • Missing directory index pages = 0

因此下文第 3 节保留的是“本轮原始发现快照”，不是当前仍未处理的实时状态。

3. 已确认的结构性问题

3.1 Rendering 存在成对重复目录

当前已确认以下目录同时出现在“旧顶层位置”和“源码对应的新子模块位置”：

  • docs/api/XCEngine/Rendering/CameraRenderer
  • docs/api/XCEngine/Rendering/Execution/CameraRenderer
  • docs/api/XCEngine/Rendering/SceneRenderer
  • docs/api/XCEngine/Rendering/Execution/SceneRenderer
  • docs/api/XCEngine/Rendering/CameraRenderRequest
  • docs/api/XCEngine/Rendering/Planning/CameraRenderRequest
  • docs/api/XCEngine/Rendering/SceneRenderRequestPlanner
  • docs/api/XCEngine/Rendering/Planning/SceneRenderRequestPlanner
  • docs/api/XCEngine/Rendering/SceneRenderRequestUtils
  • docs/api/XCEngine/Rendering/Planning/SceneRenderRequestUtils
  • docs/api/XCEngine/Rendering/RenderCameraData
  • docs/api/XCEngine/Rendering/FrameData/RenderCameraData
  • docs/api/XCEngine/Rendering/RenderResourceCache
  • docs/api/XCEngine/Rendering/Caches/RenderResourceCache
  • docs/api/XCEngine/Rendering/RenderSceneExtractor
  • docs/api/XCEngine/Rendering/Extraction/RenderSceneExtractor
  • docs/api/XCEngine/Rendering/RenderSceneUtility
  • docs/api/XCEngine/Rendering/Extraction/RenderSceneUtility

这说明文档树里同时保留了“旧的平铺布局”和“新的源码子模块布局”。后续必须只保留源码对应路径，旧路径下的内容要迁移或删除，不能继续并存。

3.2 Rendering 还有一批疑似旧命名/旧抽象残留

当前已确认下列目录没有直接对应到当前真实头文件命名，属于优先审计对象：

  • docs/api/XCEngine/Rendering/ObjectIdEncoding
  • docs/api/XCEngine/Rendering/ObjectIdPass
  • docs/api/XCEngine/Rendering/RenderMaterialUtility
  • docs/api/XCEngine/Rendering/VisibleRenderObject

这些目录大概率分别对应：

  • 已下沉或改名后的 Picking/ObjectIdCodec
  • Passes/BuiltinObjectIdPass
  • Materials/RenderMaterialResolve
  • FrameData/VisibleRenderItem

但不能直接机械删除，必须先做“旧页内容是否需要迁移”的核对。

3.3 Editor 仍保留已脱离源码的历史页

当前已确认：

  • docs/api/XCEngine/Editor/panels/XCUIDemoPanel/XCUIDemoPanel.md

对应源码：

  • editor/src/panels/XCUIDemoPanel.h
  • editor/src/panels/XCUIDemoPanel.cpp

这两个文件都已经不存在。

当前仍引用该历史页的文档包括：

  • docs/api/XCEngine/Editor/panels/panels.md
  • docs/api/XCEngine/Editor/XCUIBackend/ImGuiTransitionBackend/ImGuiTransitionBackend.md

docs/api/XCEngine/UI/DrawData/DrawData.md 里已经改成“旧链路说明”，这类描述可以保留，但不应该继续把 XCUIDemoPanel 作为真实 canonical API 页面入口。

3.4 审计明确缺页仍然存在

最新审计仍明确指出以下缺口需要补齐：

  • XCEngine/Components/VolumeRendererComponent.h
  • XCEngine/Rendering/FrameData/VisibleVolumeItem.h
  • XCEngine/Rendering/Passes/BuiltinSelectionMaskPass.h
  • XCEngine/Rendering/Passes/BuiltinSelectionOutlinePass.h
  • XCEngine/Rendering/Passes/BuiltinVolumetricPass.h
  • XCEngine/Resources/Volume/VolumeField.h
  • XCEngine/Resources/Volume/VolumeFieldLoader.h
  • XCEngine/UI/Widgets/UIDragDropInteraction.h
  • XCEngine/UI/Widgets/UIScrollModel.h
  • editor/src/ComponentEditors/VolumeRendererComponentEditor.h
  • editor/src/panels/MaterialInspectorMaterialState.h
  • editor/src/panels/MaterialInspectorMaterialStateIO.h

同时还缺少：

  • docs/api/XCEngine/Resources/Volume/Volume.md

3.5 当前存在并发修改热点

当前工作区里已有其他会话在修改以下源码区域，对应文档重构要么延后，要么单独协调：

  • editor/src/Viewport/**
  • engine/include/XCEngine/RHI/**
  • engine/include/XCEngine/Rendering/Passes/**
  • engine/include/XCEngine/Rendering/Materials/RenderMaterialResolve.h
  • engine/include/XCEngine/UI/Widgets/UISelectionModel.h
  • engine/include/XCEngine/UI/Widgets/UIDragDropInteraction.h

因此本轮执行要按“低冲突优先”组织阶段，避免多个会话同时改同一批文档。

4. 本轮目标

4.1 结构目标

  • docs/api/XCEngine/** 内每一个类/模块页都必须与当前真实源码路径平行。
  • 同一 API 只能保留一个 canonical 位置。
  • 旧的错位目录必须迁移或移除，不能继续保留作第二入口。

4.2 内容目标

  • 在结构对齐完成后，再逐批做内容重构。
  • 内容必须基于当前源码与测试，而不是沿用旧说明。

4.3 协作目标

  • 每一批任务都要能被多个会话独立领取。
  • 每一阶段结束后立即提交并推送，避免长时间悬空。

5. 分阶段执行

Phase A：建立新计划与任务板

  • 新开第二轮计划文件
  • 新开第二轮并行任务板
  • 标清“当前确定的问题”和“并发风险路径”

Phase B：清理已确认的失效历史页

  • 处理 XCUIDemoPanel
  • 修复所有反向链接
  • 让 Invalid source refs 归零

Phase C：Rendering 目录结构归位

  • 把所有错位的顶层 Rendering 目录迁移到真实子模块
  • 合并旧目录里的方法页/细页到正确的新位置
  • 删除旧顶层重复入口

Phase D：补齐审计明确缺页

  • Resources/Volume
  • Components/VolumeRendererComponent
  • Rendering/VisibleVolumeItem
  • Rendering 的体积/选择 pass
  • UI/Widgets 新 helper
  • Editor 的体积组件编辑器与材质状态页

Phase E：高风险模块内容回归

在相关源码停止波动后，再处理：

  • RHI
  • Rendering/Passes
  • Rendering/Materials
  • Editor/Viewport
  • UI/Widgets

Phase F：总回归

  • 全量跑审计
  • 清理空目录、错链、旧入口
  • 更新阶段状态并准备下一轮内容重构

6. 本轮优先级判断

当前最优先的不是继续写新内容，而是先把“错层级”和“重复入口”消掉。否则后面无论哪个会话补文档，都有较高概率继续写到旧路径。

因此第二轮的第一主战场是：

  • docs/api/XCEngine/Rendering

第二主战场是：

  • docs/api/XCEngine/Editor 中仍脱离真实源码的历史页

第三主战场才是：

  • 审计明确缺页的 Volume / UI / Editor 补齐

7. 阶段收口要求

每完成一个阶段，必须执行：

  1. 本地核对改动范围
  2. python -B docs/api/_tools/audit_api_docs.py
  3. git commit
  4. git push

只有在上一阶段已经提交推送后，才进入下一阶段。

Reference in New Issue View Git Blame Copy Permalink