C# 中 XML 文档注释的替代方法

Question

当询问 C# 代码中文档注释的约定时，答案总是导致使用 XML 注释。Microsoft 本身也推荐这种方法。https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments

/// <summary>
/// This is an XML comment.
/// </summary>
void Foo();

但是，在检查 Microsoft 的代码（例如 ASP.NET Core）时，注释看起来像这样。

//
// Summary:
//     A builder for Microsoft.AspNetCore.Hosting.IWebHost.
public interface IWebHostBuilder

包含的文档生成工具是否符合此约定，或者是否有使用此约定而不是 XML 的文档生成工具？为什么微软在他们的代码中使用这个约定而不是他们自己推荐的 XML 注释？

Answer 1

为什么 Microsoft 在他们的代码中使用这种约定而不是他们自己推荐的 XML 注释？

C# 文档注释提供了一种精确的语法，用于编码多种类型的内容和引用，例如类型、参数、URL 和其他文档文件。它使用 XML 来完成此任务，因此继承了 XML 的冗长性。请记住，XML 注释可以追溯到 C# 版本 1，当时它是一种比现在详细得多的语言。

为了避免 XML 的可读性问题，Visual Studio 以简化的纯文本格式显示注释。您无法通过编译器运行此格式。例如，如果注释包含术语customerId，则它是指方法参数还是类字段可能会产生歧义。这种歧义发生的频率很低，对人类来说不构成问题。

理想情况下，有一种针对编译器输入明确定义的单一格式，具有良好的可读性，可以避免样板文件。有一个问题需要对注释语法进行现代化改造，但不幸的是，它在 3 年内没有任何进展。