SHFB项目中枚举常量数值格式化与搜索功能优化

在软件开发文档生成工具SHFB中，枚举常量的数值显示格式和搜索功能存在一个值得注意的技术细节。当枚举常量包含数值时（如错误代码1000），默认情况下系统会将其格式化为带有千位分隔符的形式（如"1,000"），这可能导致用户在搜索时无法直接匹配到原始数值。

问题本质分析

最初开发者误以为搜索失效是由于数值格式化导致的，但深入分析后发现核心问题在于：

1. 搜索索引构建时会自动过滤掉包含数字的单词
2. 系统默认会将文本按非字母字符进行分割，导致格式化后的数值（如"1,000"）被拆分为多个片段

技术解决方案

项目维护者提出了两个潜在改进方向：

1. 索引优化方案：修改搜索索引构建逻辑，允许包含数字的单词被索引。但这种方法对于已格式化的数值（含逗号分隔符）仍存在分割问题。

2. 显示格式方案：增加配置选项，允许开发者选择是否对整型枚举值显示千位分隔符。当禁用分隔符时，数值将保持原始格式（如"1000"），既提升可读性又保证搜索准确性。

最佳实践建议

对于需要频繁搜索枚举值（特别是错误代码）的项目文档，建议：

• 优先采用无分隔符的数值显示方式
• 在文档注释中同时包含格式化和非格式化的数值说明
• 考虑在枚举摘要中增加额外的搜索关键词

实现展望

该优化将显著提升以下场景的用户体验：

• 错误代码查询
• API常量引用查找
• 数值型枚举的跨文档搜索

通过这样的改进，SHFB将能更好地服务于包含大量数值型枚举的框架文档生成需求，如系统级API文档或硬件相关开发文档。