SHFB项目中类名以下划线开头的文档生成问题解析

问题背景

在使用SHFB（Sandcastle Help File Builder）2024.12.21.0版本为FolkerKinzel.Helpers类库生成文档时，发现一个特殊现象：命名空间FolkerKinzel.Helpers.Polyfills中的所有类（类名均以下划线开头，如_ArgumentNullException）在生成的网站文档中完全缺失，而通过Open XML方式生成的文档则正常显示。

问题分析

经过深入调查和测试，发现这个问题实际上与类名是否以下划线开头无关。真正的原因在于文档生成过程中的两个关键因素：

1. 文档程序集版本问题：当公共类没有出现在生成的文档中时，最常见的原因是文档程序集不是最新版本。这通常发生在项目配置（Debug或Release）未同步更新时。

2. 本地文件系统查看限制：当直接在本地文件系统中双击打开生成的HTML文件时，现代浏览器出于安全考虑会阻止脚本执行，这会导致目录树(TOC)显示不完整。特别是对于包含特殊命名规则的类，这种问题更容易显现。

解决方案

针对上述问题，开发者可以采取以下解决方案：

1. 强制重建项目：确保使用最新的文档程序集。在Visual Studio中执行完整的重新生成操作，特别是确认使用了正确的构建配置（Debug或Release）。

2. 正确的文档查看方式：

   • 在Visual Studio中使用"View Help File"选项
   • 使用SHFB的独立GUI工具查看
   • 通过IIS等Web服务器环境查看，确保脚本能够正常执行

最佳实践建议

为了避免类似问题，建议开发者在文档生成过程中注意以下几点：

1. 定期清理和重建：在重要文档生成前执行"Clean"操作，然后进行完整重建。

2. 多环境验证：生成的文档应在多种环境下验证，包括本地Web服务器环境和直接文件系统访问。

3. 命名规范：虽然下划线开头的类名不会影响文档生成，但考虑到C#编码规范，除非有特殊需求，否则应避免使用下划线作为类名的开头。

4. 日志检查：即使没有报错，也应仔细检查生成日志，寻找可能的警告信息。

通过遵循这些实践，可以确保SHFB生成的文档完整准确地反映项目中的所有公共API，包括那些具有特殊命名约定的类。