feat: mcpp doc — 集成 doxygen + 用模块图修复跨模块引用 (cargo doc 式注释转文档)

[lildengzi]

动机

cargo doc 把注释转成文档，让开发者专注实现而不是到处找文档。希望 mcpp 提供同等的 mcpp doc 能力。

Doxygen 的注释语法（///、/** */、@brief/@param/@return）已是 C++ 生态的事实标准，读起来和 rustdoc 一样自然，因此不需要发明新格式，直接沿用 doxygen 语法即可。核心问题不是"要不要 doxygen"，而是 doxygen 单独跑在 C++20 modules 项目上时，跨模块引用是断的——而这个恰恰是 mcpp 唯一掌握完整模块图、能补上的点。

实验证据（doxygen 1.16.1，实际跑过）

构造了一个中等复杂度的模块化项目（/home/lildengzi/.local/doxygen-modules-test）：

• 主模块 engine + 两个模块分区 :shapes、:render
• 跨分区 import、模板（Point<T>/Canvas<Pixel>）、继承（Circle : Shape）、PImpl
• 消费者 main.cpp import engine; 后使用 Circle/Renderer

doxygen 1.16.1 能做对的部分：

• ✅ 正确识别 engine 模块，把 :shapes/:render 分区的导出符号聚合到模块页
• ✅ 类内文档完整：@brief/@param/@return、///< 行尾成员注释都正常
• ✅ 继承图双向链接（Circle → Shape）

明确断掉的部分（cargo doc 能跨模块跳转，doxygen 不行）：

• ❌ 消费者模块里 import engine; 后的类型无法链接回定义——main.cpp 用的 Circle/Renderer 在生成的 HTML 里没有任何跳转链接。doxygen 把 import 进来的符号当成"未知/本地符号"，模块边界处引用图中断。

这正是差异：cargo doc 会把 use crate::engine::Circle 生成定义跳转；doxygen 对 import engine; 之后的使用做不到。

提议

mcpp doc 子命令，走"集成 doxygen + 用模块图修补跨模块引用"路线：

1. mcpp doc 从 mcpp.toml 的 sources/依赖自动生成 doxygen 配置（INPUT、EXTENSION_MAPPING=cppm=C++、INCLUDE_PATH 指向依赖头）。
2. 用 mcpp 的模块图（modgraph）生成跨模块引用补丁（doxygen tagfile/别名映射），修复"消费者 import 后无法跳转定义"的断链。
3. 输出到 target/doc/，与 target/ 其他产物一致。

对比：cargo doc 底层调用 rustdoc 而非重写它；mcpp doc 同样应调用 doxygen 而非重写。差异化价值 = mcpp 掌握的模块依赖拓扑（doxygen 单独跑时完全不知道的）。

范围 / 非目标

• 不重写 doc 引擎；////doxygen 语法直接沿用。
• 裸机/freestanding 与本文档无关。
• 第一版可以只覆盖 hosted 目标。

备注

实验项目已保留在本地可复现；Doxyfile 配置也一并留档。