“所有高质量 API 文档的基础，都是源码里的注释。”这句话出自 UDE 团队最近的博客文章，也是整个文档自动生成流水线重构的起点。在大规模 C++ 项目中，注释就是唯一的真源，没有它们，任何自动文档生成都无从谈起。真正的问题是，怎么把这些注释变成一个现代化、访问飞快、方便开发者查阅的站点。

可现实太骨感了。C++ 圈子最主流的工具 Doxygen，原生输出不是 HTML 就是 XML，而这俩格式偏偏接不进 Hugo、Docusaurus、VitePress 这些现代静态站点生成器，因为它们在入口处只认 Markdown。于是就有了那个让人头疼的“三件套”：Doxygen 先生成 XML，然后用 DoxyBook2 把 XML 转成 Markdown，最后再喂给 Hugo 构建。能跑，但毛病一堆。

打开网易新闻 查看精彩图片

第一，根本没可扩展性。转换器每次都要把整张 XML 实体图一口气吞进内存，碰上带几万个类和方法的大号 SDK，眨眼就撞上内存天花板，处理时间也长得离谱。第二，想定制输出简直反人类。这些工具当初就没打算让你灵活切换多种样式，想在同一个流程里输出多种排版格式，配置起来能让人血压拉满。

UDE 的做法很简单——把中间那块多余的转换步骤直接砍掉。它的流水线分三道关：Collector 直接从源码中把注释和结构信息抓出来；Parser 再把这些数据翻译成一种语言无关的中间表示（IR），不依赖任何特定变成语言；最后 Renderer 拿着这份 IR，瞬间组装出任意目标静态站点生成器要的 Markdown 或 HTML，中间连一行 XML 的影子都没有。没有额外的转换环节，从一个单一的 IR 源就能渲染出你想要的任何格式。

对于大项目，构建时间就是命。UDE 用的是增量缓存，每次只重新计算真正变动的那部分，不用把整个实体图重新加载一遍。而且整个流水线跨平台丝滑一致，本地 Windows、CI 上的 Linux 跑起来完全同款；同时它还践行“文档即代码”，把“文档应该记录什么”的配置和代码版本锁在一起，在同一条 CI 流水线里编译构建。

不过 UDE 也没有假装自己能包办一切。从代码自动生成的 API 参考回答的是“函数和类怎么组织”这类结构性问题，却没法告诉你“为了完成某个具体的业务需求，应该按什么顺序去调用它们”。这正是 DevGuide 这类人工撰写的教程和文章要解决的问题。UDE 的策略不是取代人工，而是无缝衔接——自动生成的 API 参考始终保持完整且永远最新，这些自然和人工指南一块儿，躺在你选的现代静态站点里。