SandCastle Help File Builder报错：提示缺少Summary和Param但实际存在

问题现象 #

在Visual Studio 2022中使用SandCastle Help File Builder生成C#帮助文档时，出现以下异常：

• 生成的文档中显示红色提示“缺少summary”或“缺少param”
• 对应方法的代码中已添加完整的XML注释，且生成的XML注释文件中确实包含<summary>和<param>节点
• 已将XML注释文件和程序集文件添加至Documentation Sources中

排查与解决步骤 #

1. 验证XML注释与方法签名的匹配度 #

确认XML注释文件中方法的完全限定名（包含命名空间、类名、完整方法签名）和程序集中的方法完全一致。SandCastle通过签名关联注释，若参数类型的完全限定名（比如System.String和string）、方法重载签名存在细微差异，会导致注释匹配失败。

2. 清理并重新生成注释文件 #

• 在Visual Studio中执行Build > Clean Solution清理项目缓存，再通过Build > Rebuild Solution重新生成XML注释文件，确保文件内容为最新版本。
• 用VS自带的XML编辑器打开注释文件，检查是否存在未闭合标签、特殊字符未转义等格式错误，这类错误会导致SandCastle无法解析注释。

3. 检查SandCastle项目配置 #

• 打开SandCastle Help File Builder项目，进入Documentation Sources面板，确认程序集和XML文件的路径正确，未添加旧版本的冗余文件。
• 进入Comments > Visibility配置项，确认当前方法的可见性级别（如public）在设置的可见范围内，且未勾选“忽略指定注释类型”的选项。

4. 更新SandCastle版本 #

旧版本SandCastle可能存在VS2022兼容性问题，前往官方仓库下载最新版本替换旧版本后，重新生成帮助文档。

5. 排查方法重载的注释 #

若该方法存在重载，确认每个重载都添加了独立且正确的XML注释，避免因重载签名混淆导致SandCastle无法识别对应注释。

内容的提问来源于stack exchange，提问作者user14204486