更新:2007 年 11 月
使用 XML doc 注释需要分隔符,分隔符为编译器指示文档注释的起止位置。XML 文档标记可以与以下几种分隔符一起使用:
使用 /** */ 分隔符时有一些格式设置规则:
对于包含 /** 分隔符的行,如果该行的其余部分为空白,则不将该行处理为注释。如果第一个字符为空白,则忽略此空白字符并处理该行的剩余部分。否则,将 /** 分隔符后的整行文本处理为注释的一部分。
对于包含 */ 分隔符的行,如果到 */ 分隔符为止仅有空白,则忽略该行。否则,将到 */ 分隔符为止的那行文本处理为注释的一部分,同时必须遵循以下描述的模式匹配规则。
对于以 /** 分隔符开头的行后面的那些行,编译器会在每个行的开头寻找一个公共模式,这些行由可选的空白和星号 (*) 以及后面更多可选的空白组成。如果编译器在每行的开头均找到了一组公共的字符,则它将对 /** 分隔符到包含 */ 分隔符的行(可能包括此行)之间的所有行忽略该模式。
示例:
以下注释中将被处理的唯一部分是以 <summary> 开头的行。下列两个标记格式将产生相同的注释:
/**
<summary>text</summary>
*/
/** <summary>text</summary> */
编译器在第二行和第三行的开头应用“*”模式进行忽略。
/**
* <summary>
* text </summary>*/
编译器在此注释中找不到任何模式,因为第二行没有星号。因而,第二行和第三行直到 */ 的所有文本都将被处理为注释的一部分。
/**
* <summary>
text </summary>*/
编译器之所以在此注释中没找到任何模式有两个原因。首先,行首星号前的空格数目不一致。其次,第五行是以 Tab 开头的,它并不等效于空格。因而,从第二行到 */ 的所有文本都将被处理为注释的一部分。
/**
* <summary>
* text
* text2
* </summary>
*/