这是一篇关于 Swift 语言文档系统 DocC 代码的技术深度剖析文章，主要内容如下：

• 问题发现：在为 DocC 中的代码片段功能编写文档时，遇到文档预览机制的问题，添加代码片段后文档预览约有一半时间失败，最初以为是 swift-docc-plugin 的问题，后来发现是间歇性问题，通过一系列命令验证行为并确定是添加第一个代码片段时开始出现问题，同时另一个项目 swift-markdown 从未出现此问题。

• 调试过程：

  • 尝试通过 SwiftPM 插件的调试很麻烦，最终通过在插件代码中添加 sleep 命令并通过终端找到进程 ID 来附加调试器，但发现不需要调试插件，因为 docc 的preview命令又调用了另一个进程。
  • 关闭在插件中的问题并在 swift-docc 中打开新问题，总结所学和重现问题的步骤，在不同版本的 docc 中重复验证问题，包括从 Swift 工具链发布的版本到main分支。
  • 为了方便调试，在 Xcode 中设置环境变量和参数来运行 docc，通过比较不同状态下的目录结构找到问题所在，即顶级模块在输出中缺失。

• 深入研究：

  • DocC 的核心是转换过程，将符号图和文档目录转换为文档存档，符号图由编译器生成，在转换过程中清理和重新排列符号之间的关系等信息。
  • 在转换代码中通过 printf 调试追踪问题，发现问题出现在knownPages的过滤操作上，isVirtual属性的设置影响了模块的渲染，进一步研究发现isVirtual来自编译器，符号图加载器的逻辑存在缺陷，导致加载的符号图中模块节点的设置不正确。
• 解决方案：经过 3 天的工作，报告了 3 个问题并提出解决方案，在 SymbolKit 中修改逻辑以支持“只能有一个主符号图”的基本假设，同时在 DocC 中提交补充 PR 以消除重复逻辑，主要问题有望通过 SymbolKit 的更改得到完全解决。