Читать «C# 4.0 полное руководство - 2011» онлайн - страница 647
Герберт Шилдт
Документирующие комментарии вводятся перед объявлением таких элементов языка С#, как классы, пространства имен, методы, свойства и события. С помощью документирующих комментариев можно вводить в исходный текст программы сведения о самой программе. При компиляции программы документирующие комментарии к ней могут быть помещены в отдельный XML-файл. Кроме того, документирующие комментарии можно использовать в средстве IntelliSense интегрированной среды разработки Visual Studio.
Дескрипторы XML-комментариев
В С# поддерживаются дескрипторы документации в формате XML, сведенные в табл. 1. Большинство дескрипторов XML-комментариев не требует особых пояснений
и действуют подобно всем остальным дескрипторам XML, знакомым многим программистам. Тем не менее дескриптор <list> — сложнее других. Он состоит из двух частей: заголовка и элементов списка. Ниже приведена общая форма дескриптора
<list>:
<listheader>
<term> имя </term>
.<description> текст </description>
</listheader>
где текст описывает имя. Для описания таблиц текст не используется. Ниже приведена общая форма элемента списка:
<item>
<term> имя_элемента </term>
<description> текст </description>
</item>
где текст описывает имя_элемента. Для описания маркированных и нумерованных списков, а также таблиц имя элемента не используется. Допускается применение нескольких элементов списка <item>.
Таблица 1. Дескрипторы XML-комментариев
Дескриптор
Описание
<с> код </с>
Определяет текст, на который указывает код, как программный код
<code> код </code>
Определяет несколько строк текста, на который указывает код, как программный код
<example> пояснение </example>
Определяет текст, на который указывает пояснение, как описание примера кода
<exception cref = "имя">
Описывает исключительную ситуацию, на ко
пояснение </exception>
торую указывает имя
<include file = 1fname1 path =
Определяет файл, содержащий XML-kom-
'path[0tagName = "tagID 11 ] ' />
ментарии для текущего исходного файла. При
этом fname обозначает имя файла; path — путь к файлу; tagName — имя дескриптора; tagID — идентификатор дескриптора
<list type = "тип""> заголовок
Определяет список. При.этом тип обозначает
списка элементы списка </list>
тип списка, который может быть маркированным, нумерованным или таблицей
<рага> текст </para>
Определяет абзац текста в другом дескрипторе
<param name = 'имя параметра'>