Разделители для тегов в документации (Руководство по программированию на C#)

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

• ///
  Однострочный разделитель.Это форма, представленная в примерах документов и используемая в шаблонах проектов Visual C#.Если после разделителя имеется символ пробела, этот символ не включается в выходные данные XML.

  Примечание
  В интегрированной среде разработки Visual Studio имеется функция автоматического редактирования комментариев Smart Comment Editing, которая автоматически вставляет теги <summary>и</summary> и перемещает курсор в этих тегах после ввода разделителя /// в редакторе кода.Для доступа к этой функции используйте "Параметры", "Текстовый редактор", C#, "Форматирование" на страницах свойств проекта.

• /** */
  Многострочные разделители.

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

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

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

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

Эти правила показаны в следующем примере.

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

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

• Компилятор обнаруживает в начале второй и третьей строки общий шаблон " * ".Шаблон не будет включен в выходные данные.

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

• Компилятор не обнаружил общий шаблон в следующем примечании, так как второй знак в третьей строке не является звездочкой.Следовательно весь текст во второй и третьей строках, обрабатывается как часть примечания.

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

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

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

См. также

Ссылки

Комментарии к XML-документации (Руководство по программированию на C#)

/doc (параметры компилятора C#)

Комментарии к XML-документации (Руководство по программированию на C#)

Основные понятия

Руководство по программированию на C#