Поделиться через


Разделители для тегов в документации (Руководство по программированию на 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#