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

Question

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

14

当问及C#代码文档注释的惯例时，答案总是指向使用XML注释。微软自己也推荐这种方法。https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments

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

然而，当检查微软的代码，例如ASP.NET Core时，注释看起来是这样的。

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

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

- user8190030

1

看起来检查器显示的不同，因为他们在源代码中使用了XML注释：https://github.com/aspnet/AspNetCore/blob/425c196cba530b161b120a57af8f1dd513b96f67/src/Hosting/Abstractions/src/IWebHostBuilder.cs#L14 - marcusturewicz

很奇怪。在使用Visual Studio和VSCode进行检查时，它显示了这种YAML样式的标记。此外，检查器仍然可以在弹出窗口中正确地显示注释。也许有某种转换步骤正在进行。 - user8190030

1

猜测检查员这样显示可能是因为对于人类来说，这比XML更易读。 - marcusturewicz

看起来像是Natural docs，它完全支持C#。我不喜欢XML注释，我觉得它们太过于繁琐了。 - Jean Gregory

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Edward Brey · Accepted Answer

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

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

为了避免 XML 的可读性问题，Visual Studio 以简化的纯文本格式显示注释。你无法将这种格式重新运行通过编译器。例如，如果一个注释包含术语 "customerId"，那么它可能不清楚它是指方法参数还是类字段。这种歧义不经常发生，对人类来说不是问题。

理想情况下，应该存在一种单一的格式，它具有良好的可读性，避免使用样板文件来定义编译器的输入。有一个问题正在进行中，旨在现代化注释语法，但不幸的是，这个问题已经悬而未决了3年。