Jazzy项目中基于文件自动分组全局符号的技术方案

背景介绍

Jazzy作为Swift和Objective-C项目的文档生成工具，在处理大型代码库时面临着如何有效组织全局常量和函数的挑战。当前版本虽然支持通过custom_categories手动配置分组，但随着项目规模增长，这种方式会带来显著的维护负担。

现有机制分析

Jazzy现有的分组机制主要依赖custom_categories配置项，它允许用户手动指定符号的分组关系。这种方式虽然灵活，但存在两个主要问题：

1. 维护成本高：每当新增全局符号时，都需要手动更新配置文件
2. 扩展性差：无法根据文件来源自动组织相关符号

技术实现方案

核心数据结构

实现自动分组功能需要理解Jazzy的核心数据结构：

1. SourceDeclaration：表示源代码中的声明，包含以下关键属性：

   • name：本地名称（如myMethod(arg:)）
   • fully_qualified_name：模块内全限定名（如MyClass.myMethod(arg:)）
   • file：源文件路径（在符号图模式下可能为nil）

2. DocIndex：所有SourceDeclaration构成的搜索树，提供了高效的符号查找能力

分组算法设计

基于文件的自动分组算法可以按以下步骤实现：

1. 收集候选符号：遍历DocIndex中的所有SourceDeclaration
2. 匹配文件模式：支持多种匹配方式：
   • 精确文件名匹配
   • 通配符模式（如*Utils.swift）
   • 正则表达式匹配
3. 构建分组结构：为每个匹配的文件模式创建对应的文档分组
4. 稳定排序：确保生成的子项顺序固定，保证输出一致性

特殊场景处理

需要考虑的特殊情况包括：

1. 符号图模式：当Jazzy运行在符号图模式时，file属性可能为nil，需要优雅降级
2. 跨文件符号：处理那些定义分散在多个文件中的相关符号
3. 命名冲突：避免不同文件中同名符号的冲突

实现建议

对于希望贡献此功能的开发者，建议采用以下实现策略：

1. 扩展custom_categories语法：支持新的匹配语法，如file:GlobalUtils.h和regex:*CommonPattern*
2. 增强Grouper模块：在现有分组逻辑基础上增加基于文件的自动分组能力
3. 保持向后兼容：确保新功能不影响现有的手动分组方式

技术价值

这一改进将为Jazzy带来显著的技术优势：

1. 降低维护成本：减少手动配置分组的工作量
2. 提升可扩展性：自动适应项目规模的增长
3. 改善文档质量：通过逻辑分组使生成的文档更易于理解

总结

基于文件自动分组全局符号的功能将极大提升Jazzy在处理大型代码库时的文档生成能力。这一改进不仅解决了当前手动配置的痛点，还为未来的功能扩展奠定了良好基础。实现过程中需要注意处理各种边界情况，并保持与现有功能的兼容性，确保平稳过渡。