Разделители для тегов документации по Visual C++

Для использования тегов документации требуются разделители, указывающие компилятору, где начинается и заканчивается комментарий документации.

С тегами в XML-документации можно использовать следующие виды разделителей:

Разделитель	Description
///	Это форма, показанная в примерах документации и используемая шаблонами проектов Visual Studio C++.
/** */	Это многострочные разделители.

На использование разделителей /** */ распространяется несколько правил форматирования.

• Для строки, содержащей /** разделитель, если остальная часть строки является пробелами, строка не обрабатывается для комментариев. Если первый символ является пробелом, этот символ пробела игнорируется, а остальная часть строки обрабатывается. В противном случае весь текст, расположенный в строке после разделителя /**, обрабатывается как часть комментария.

• Если в строке, содержащей */ разделитель, есть только пробелы до */ разделителя, эта строка игнорируется. В противном случае текст строки, расположенный перед разделителем */, обрабатывается как часть комментария, и к нему применяются правила сопоставления шаблонов, описанные в следующем разделе.

• Для строк после того, как он начинается с /** разделителя, компилятор ищет общий шаблон в начале каждой строки, состоящей из необязательных пробелов и звездочки (*), за которым следует больше дополнительного пробела. Если компилятор находит общий набор символов в начале каждой строки, он игнорирует этот шаблон для всех строк после разделителя /** вплоть до самой строки, содержащей разделитель */, и, возможно, включая ее.

Примеры

• В следующем комментарии будет обработана только строка, которая начинается с <summary>. Следующие форматы с двумя тегами позволяют создать точно такие же комментарии.

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

• Компилятор применяет шаблон " * " для игнорирования в начале второй и третьей строки.

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

• Компилятор не находит шаблон в этом комментарии, так как на второй строке нет звездочки. Весь текст во второй и третьей строках до тех пор, пока не */будет обработан в рамках комментария.

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

• Компилятор не обнаруживает шаблон в этом комментарии по двум причинам. Во-первых, нет строки, начинающейся с согласованного количества пробелов перед звездочкой. Во-вторых, пятая строка начинается с символа табуляции, который не является пробелом. Весь текст из второй строки, пока не */ будет обработан как часть комментария.

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

См. также

XML-документация