采用顶级语句的C#程序中XML文档注释为何无法正常生效？

在使用C#顶级语句的项目中，直接写在顶级语句作用域里的本地函数，默认不会被编译器纳入XML文档解析范围：

• 顶级语句会被编译器隐式包装到一个名为<Main>$的隐藏全局类的入口方法中，你定义的Summarize本质是这个入口方法里的嵌套本地函数
• Visual Studio的三斜杠自动生成注释模板、鼠标悬停显示注释的功能，完全依赖编译器输出的XML文档数据，默认配置下编译器不会处理这类嵌套本地函数的XML注释，就会出现注释不生效的现象。

方案1：修改项目配置启用本地函数注释支持（适用于Visual Studio 2022 17.4及以上版本） #

1. 在解决方案资源管理器中右键项目节点，选择「编辑项目文件」，打开后缀为.csproj的项目配置文件
2. 找到文件中的<PropertyGroup>配置段，在其中加入以下两项配置：

<GenerateDocumentationFile>true</GenerateDocumentationFile>
<DocumentationMode>All</DocumentationMode>

3. 保存配置文件后，关闭重新打开Visual Studio加载项目，三斜杠自动补全、悬停显示注释的功能就会恢复正常。

方案2：将带注释的方法迁移到普通类中（全版本兼容） #

如果使用的是较低版本的Visual Studio，不支持上述配置项，可以把需要添加XML注释的方法放到显式定义的静态类中，顶级语句仅保留入口执行逻辑，参考写法：

// 顶级语句仅作为程序入口写执行逻辑
MathUtils.Summarize(15, 35);

/// <summary>
/// 计算两个整型数值的和
/// </summary>
/// <param name="a">第一个参与计算的整数</param>
/// <param name="b">第二个参与计算的整数</param>
/// <returns>两个整数相加的计算结果</returns>
public static class MathUtils
{
    public static int Summarize(int a, int b)
    {
        return a + b;
    }
}

这种写法没有版本兼容问题，XML注释的所有功能都可以正常生效。

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