XML 文档注释(C# 编程指南)XML documentation comments (C# programming guide)

使用 C#,可以通过以下方式为代码创建文档:将特殊注释字段中的 XML 元素包含在源代码中注释引用的代码块的前面,例如:In C#, you can create documentation for your code by including XML elements in special comment fields (indicated by triple slashes) in the source code directly before the code block to which the comments refer, for example.

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

使用 -doc 选项进行编译时,编译器会在源代码中搜索所有 XML 标记,并创建一个 XML 文档文件。When you compile with the -doc option, the compiler will search for all XML tags in the source code and create an XML documentation file. 若要基于编译器生成的文件创建最终文档,可以创建一个自定义工具,也可以使用 DocFXSandcastle 等工具。To create the final documentation based on the compiler-generated file, you can create a custom tool or use a tool such as DocFX or Sandcastle.

若要引用 XML 元素(例如,你的函数将处理你要在 XML 文档注释中描述的特定 XML 元素),你可使用标准引用机制(<>)。To refer to XML elements (for example, your function processes specific XML elements that you want to describe in an XML documentation comment), you can use the standard quoting mechanism (< and >). 若要引用代码引用 (cref) 元素中的通用标识符,可使用转义字符(例如,cref="List&lt;T&gt;")或大括号 (cref="List{T}")。To refer to generic identifiers in code reference (cref) elements, you can use either the escape characters (for example, cref="List&lt;T&gt;") or braces (cref="List{T}"). 作为特例,编译器会将大括号解析为尖括号以在引用通用标识符时使作者能够更轻松地进行文档注释。As a special case, the compiler parses the braces as angle brackets to make the documentation comment less cumbersome to author when referring to generic identifiers.

备注

XML 文档注释不是元数据;它们不包括在编译的程序集中,因此无法通过反射对其进行访问。The XML documentation comments are not metadata; they are not included in the compiled assembly and therefore they are not accessible through reflection.

本节内容In this section

有关详细信息,请参见:For more information, see:

C# 语言规范C# language specification

有关详细信息,请参阅 C# 语言规范For more information, see the C# Language Specification. 该语言规范是 C# 语法和用法的权威资料。The language specification is the definitive source for C# syntax and usage.

请参阅See also