XML文档注释

C# 源文件可以具有结构化注释，这些注释生成这些文件中定义的类型的 API 文档。 C# 编译器会生成一个 XML 文件，其中包含表示注释和 API 签名的结构化数据。 例如，其他工具可以处理该 XML 输出，以网页或 PDF 文件的形式创建人类可读的文档。

此过程为你在代码中添加 API 文档提供了许多好处：

• C# 编译器将 C# 代码的结构与注释文本结合到单个 XML 文档中。
• C# 编译器会验证注释是否与相关标记的 API 签名相匹配。
• 处理 XML 文档文件的工具可定义特定于这些工具的 XML 元素和属性。

Visual Studio 等工具为文档注释中使用的很多常用 XML 元素提供 IntelliSense。

本文将介绍这些主题：

• 文档注释和 XML 文件生成
• 由 C# 编译器和 Visual Studio 验证的标记
• 生成的 XML 文件的格式

创建 XML 文档输出

通过编写由三斜杠指示的特殊注释字段，可以为代码创建文档。 注释字段包含用于描述注释后面的代码块的 XML 元素。 例如：

C#复制

/// <summary>
///  This class performs an important function.
/// </summary>
public class MyClass {}

设置 GenerateDocumentationFile 或 DocumentationFile 选项后，编译器将在源代码中找到包含 XML 标记的所有注释字段，并根据这些注释创建 XML 文档文件。 启用此选项后，编译器将为项目中声明的所有公开可见成员生成 CS1591 警告，且没有 XML 文档注释。

XML 注释格式

XML 文档注释需要使用分隔符，这些分隔符指示文档注释开始和结束的位置。 可以将以下分隔符用于 XML 文档标记：

• /// 单行分隔符：文档示例和 C# 项目模板使用此形式。 如果分隔符后面有空格，则它不会包含在 XML 输出中。

   备注

  Visual Studio 会自动插入 <summary>