Delimitadores de marcas de documentação para o Visual C++

  • Artigo

O uso de marcas de documentação exige delimitadores, que indicam ao compilador o local em que um comentário da documentação começa e termina.

Você pode usar os seguintes tipos de delimitadores com as marcas de documentação XML:

Delimitador Descrição
/// Esse é o formato mostrado nos exemplos de documentação e usado pelos modelos de projeto do C++ do Visual Studio.
/** */ Veja abaixo os delimitadores multilinha.

Há algumas regras de formatação no uso dos delimitadores /** */:

  • Na linha que contém o delimitador /**, se o resto da linha for um espaço em branco, a linha não será processada para comentários. Se o primeiro caractere for um espaço em branco, esse caractere de espaço em branco será ignorado e o restante da linha será processado. Caso contrário, todo o texto da linha após o delimitador /** é processado como parte do comentário.

  • Na linha que contém o delimitador */, se houver apenas espaços em branco até o delimitador */, essa linha será ignorada. Caso contrário, o texto da linha até o delimitador */ é processado como parte do comentário, sujeito às regras de correspondência de padrão descritas no marcador seguinte.

  • Nas linhas após aquela que começa com o delimitador /**, o compilador procura um padrão comum no início de cada linha, que consiste em um espaço em branco opcional e um asterisco (*), seguido por mais um espaço em branco opcional. Se o compilador encontrar um conjunto comum de caracteres no início de cada linha, ele ignorará esse padrão em todas as linhas após o delimitador /**, até e, possivelmente, incluindo a linha que contém o delimitador */.

Exemplos

  • A única parte do comentário a seguir que será processada é a linha que começa com <summary>. Os dois seguintes formatos de marcação produzirão os mesmos comentários:

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

  • O compilador aplica o padrão " * " para ignorar no início da segunda e terceira linhas.

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

  • O compilador não encontra nenhum padrão nesse comentário porque não há nenhum asterisco na segunda linha. Todo o texto na segunda e terceira linhas, até o */, será processado como parte do comentário.

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

  • O compilador não encontra nenhum padrão nesse comentário por dois motivos. Primeiro porque não há nenhuma linha que começa com um número consistente de espaços antes do asterisco. Segundo, a quinta linha começa com uma guia, que não coincide com espaços. Todo o texto da segunda linha até o */ será processado como parte do comentário.

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

Confira também

Documentação XML