Visual C++ 文档标记的分隔符

文档标记需要使用分隔符,用来向编译器指示文档注释开始和结束的位置。

可以使用以下采用 XML 文档标记的分隔符:

分隔符 说明
/// 这是在文档示例中显示的格式,由 Visual Studio C++ 项目模板使用。
/** */ 这些是多行分隔符。

使用 /** */ 分隔符时,需遵守一些格式设置规则:

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

  • 对于包含 */ 分隔符的行,如果 */ 分隔符前面只有空格,则忽略此行。 否则,*/ 分隔符前面的行的文本被处理为注释的一部分,并且需符合后面的项目符号所描述的模式匹配规则。

  • 对于那些位于以 /** 分隔符开头的行之后的行,编译器会在每行的开头部分(由可选空格和星号 (*) 组成,后面是更多可选空格)寻找一个它们共同的模式。 如果编译器在每行的开头部分找到一组共同的字符,则将忽略 /** 分隔符之后所有行的这种模式,直到或者包括包含 */ 分隔符的那一行。

示例

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

    /**
    <summary>text</summary>
    */
    /** <summary>text</summary> */
    
  • 编译器应用了“*”模式,用于在第二行和第三行的开头位置进行忽略。

    /**
     * <summary>
     *  text </summary>*/
    
  • 因为在第二行上没有星号,所以编译器在此注释中没有找到模式。 第二和第三行上的所有文本(直到 */)将处理为注释的一部分。

    /**
     * <summary>
       text </summary>*/
    
  • 编译器在此注释中未找到模式,原因有两个。 首先,在所有行的开头,星号之前的空格数量都不一致。 其次,第 5 行以制表符开头,这与空格不匹配。 第二行中的所有文本(直到 */)将处理为注释的一部分。

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

另请参阅

XML 文档