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