Разделители для тегов в документации (руководство по программированию в C#)
Обновлен: Ноябрь 2007
Для создания комментариев в документах XML необходимо использовать разделители, по которым компилятор определяет начало и конец комментария. С тегами в XML-документации можно использовать следующие виды разделителей:
///
Это форма, представленная в примерах документов и используемая в шаблонах проектов Visual C#..gif "Примечание")
Примечание.В интегрированной среде разработки Visual Studio имеется функция автоматического редактирования комментариев Smart Comment Editing, которая автоматически вставляет теги <summary>и</summary> и перемещает курсор в этих тегах после ввода разделителя /// в редакторе кода. Для доступа к этой функции используйте Страница "Форматирование", папка "C#", папка "Текстовый редактор", диалоговое окно "Параметры" на страницах свойств проекта.
/** */
Многострочные разделители.
При использовании разделителей /** */ действуют несколько правил форматирования:
Строка, содержащая разделитель /** , не обрабатывается как комментарий, если оставшаяся ее часть представляет собой пробел. Если первый знак является пробелом, то этот пробел игнорируется, а оставшаяся часть строки обрабатывается. В противном случае весь текст, расположенный в строке после разделителя /**, обрабатывается как часть комментария.
Строка, содержащая разделитель */ , игнорируется, если перед разделителем */ стоит только пробел. В противном случае текст строки, расположенный перед разделителем */, обрабатывается как часть комментария, и к нему применяются правила сопоставления шаблонов, описанные в следующем разделе.
В начале каждой из строк, расположенных после строки, которая начинается с разделителя /**, компилятор выполняет поиск общего шаблона, состоящего из необязательного пробела, символа звездочки (*) и еще одного необязательного пробела. Если компилятор находит указанную последовательность знаков в начале каждой строки, он игнорирует этот шаблон для всех строк, расположенных между разделителем /** и строкой с разделителем */ (возможно, включая и ее).
Некоторые примеры.
В следующем комментарии будет обработана только строка, которая начинается с <summary>. Приведенные после этого форматы с двумя тегами позволяют создать точно такие же комментарии:
/**
<summary>text</summary>
*/
/** <summary>text</summary> */
Компилятор обнаруживает в начале второй и третьей строки шаблон « * » и игнорирует их.
/**
* <summary>
* text </summary>*/
Компилятор не обнаруживает шаблон в этом комментарии, так как на второй строке нет звездочки. Следовательно весь текст на второй и третьей строках, расположенный до */, будет обработан как часть комментария.
/**
* <summary>
text </summary>*/
Компилятор не обнаруживает шаблон в данном комментарии по двум причинам. Во-первых, отсутствует строка, на которой перед звездочкой стоит допустимое число пробелов. Во-вторых, пятая строка начинается с символа табуляции, который отличается от пробелов. Следовательно весь текст, начиная со второй строки и заканчивая */, будет обработан как часть комментария.
/**
* <summary>
* text
* text2
* </summary>
*/
См. также
Задачи
Основные понятия
Руководство по программированию в C#
Ссылки
Комментарии XML-документации (Руководство по программированию в C#)
/doc (комментарии документации процесса) (параметры компилятора C#)
Комментарии XML-документации (Руководство по программированию в C#)