文档标记需要使用分隔符,用来向编译器指示文档注释开始和结束的位置。
可以使用以下采用 XML 文档标记的分隔符:
分隔符 | 说明 |
---|---|
/// |
这是在文档示例中显示的格式,由 Visual Studio C++ 项目模板使用。 |
/** */ |
这些是多行分隔符。 |
使用 /** */
分隔符时,需遵守一些格式设置规则:
对于包含
/**
分隔符的行,如果行的其余部分为空格,则不将此行作为注释处理。 如果第一个字符为空格,则忽略此空格字符,并处理该行的其余部分。 否则,将/**
分隔符后面的行的所有文本作为注释的一部分进行处理。对于包含
*/
分隔符的行,如果*/
分隔符前面只有空格,则忽略此行。 否则,*/
分隔符前面的行的文本被处理为注释的一部分,并且需符合后面的项目符号所描述的模式匹配规则。对于那些位于以
/**
分隔符开头的行之后的行,编译器会在每行的开头部分(由可选空格和星号 (*
) 组成,后面是更多可选空格)寻找一个它们共同的模式。 如果编译器在每行的开头部分找到一组共同的字符,则将忽略/**
分隔符之后所有行的这种模式,直到或者包括包含*/
分隔符的那一行。
示例
以下注释中将被处理的唯一部分是以
<summary>
开头的行。 下列两种标记格式将产生相同的注释:/** <summary>text</summary> */ /** <summary>text</summary> */
编译器应用了“*”模式,用于在第二行和第三行的开头位置进行忽略。
/** * <summary> * text </summary>*/
因为在第二行上没有星号,所以编译器在此注释中没有找到模式。 第二和第三行上的所有文本(直到
*/
)将处理为注释的一部分。/** * <summary> text </summary>*/
编译器在此注释中未找到模式,原因有两个。 首先,在所有行的开头,星号之前的空格数量都不一致。 其次,第 5 行以制表符开头,这与空格不匹配。 第二行中的所有文本(直到
*/
)将处理为注释的一部分。/** * <summary> * text * text2 * </summary> */