更新:2007 年 11 月

使用 XML doc 注释需要分隔符,分隔符为编译器指示文档注释的起止位置。XML 文档标记可以与以下几种分隔符一起使用:

///

这是显示在文档示例中并由 Visual C# 项目模板使用的形式。

说明:

Visual Studio IDE 具有一项称为“智能注释编辑”的功能,它自动插入

标记,并且当您在代码编辑器中键入 /// 分隔符后将光标移动到这些标记内。从项目属性页的 “选项”对话框 ->“文本编辑器”->“C#”->“格式设置” 可以访问此功能。

/** */

多行分隔符。

使用 /** */ 分隔符时有一些格式设置规则:

  • 对于包含 /** 分隔符的行,如果该行的其余部分为空白,则不将该行处理为注释。如果第一个字符为空白,则忽略此空白字符并处理该行的剩余部分。否则,将 /** 分隔符后的整行文本处理为注释的一部分。

  • 对于包含 */ 分隔符的行,如果到 */ 分隔符为止仅有空白,则忽略该行。否则,将到 */ 分隔符为止的那行文本处理为注释的一部分,同时必须遵循以下描述的模式匹配规则。

  • 对于以 /** 分隔符开头的行后面的那些行,编译器会在每个行的开头寻找一个公共模式,这些行由可选的空白和星号 (*) 以及后面更多可选的空白组成。如果编译器在每行的开头均找到了一组公共的字符,则它将对 /** 分隔符到包含 */ 分隔符的行(可能包括此行)之间的所有行忽略该模式。

示例:

  • 以下注释中将被处理的唯一部分是以 <summary> 开头的行。下列两个标记格式将产生相同的注释:

    /**

    <summary>text</summary>

    */

    /** <summary>text</summary> */

  • 编译器在第二行和第三行的开头应用“*”模式进行忽略。

    /**

    * <summary>

    * text </summary>*/

  • 编译器在此注释中找不到任何模式,因为第二行没有星号。因而,第二行和第三行直到 */ 的所有文本都将被处理为注释的一部分。

    /**

    * <summary>

    text </summary>*/

  • 编译器之所以在此注释中没找到任何模式有两个原因。首先,行首星号前的空格数目不一致。其次,第五行是以 Tab 开头的,它并不等效于空格。因而,从第二行到 */ 的所有文本都将被处理为注释的一部分。

    /**

    * <summary>

    * text

    * text2

    * </summary>

    */

请参见

任务

“XML 文档”示例

概念

参考

/doc(处理文档注释)(C# 编译器选项)