C# 4.0 полное руководство - 2011

Документирующие комментарии вводятся перед объявлением таких элементов языка С#, как классы, пространства имен, методы, свойства и события. С помощью документирующих комментариев можно вводить в исходный текст программы сведения о самой программе. При компиляции программы документирующие комментарии к ней могут быть помещены в отдельный XML-файл. Кроме того, документирующие комментарии можно использовать в средстве IntelliSense интегрированной среды разработки Visual Studio.

Дескрипторы XML-комментариев

В С# поддерживаются дескрипторы документации в формате XML, сведенные в табл. 1. Большинство дескрипторов XML-комментариев не требует особых пояснений

и действуют подобно всем остальным дескрипторам XML, знакомым многим программистам. Тем не менее дескриптор — сложнее других. Он состоит из двух частей: заголовка и элементов списка. Ниже приведена общая форма дескриптора

:

имя

. текст

где текст описывает имя. Для описания таблиц текст не используется. Ниже приведена общая форма элемента списка:

имя_элемента

текст

где текст описывает имя_элемента. Для описания маркированных и нумерованных списков, а также таблиц имя элемента не используется. Допускается применение нескольких элементов списка .

Таблица 1. Дескрипторы XML-комментариев

Дескриптор

Описание

<с> код

Определяет текст, на который указывает код, как программный код

код

Определяет несколько строк текста, на который указывает код, как программный код

пояснение

Определяет текст, на который указывает пояснение, как описание примера кода

Описывает исключительную ситуацию, на ко

пояснение

торую указывает имя

1fname¹ path =

Определяет файл, содержащий XML-kom-

'path[0tagName = "tagID ¹¹ ] ' />

ментарии для текущего исходного файла. При

этом fname обозначает имя файла; path — путь к файлу; tagName — имя дескриптора; tagID — идентификатор дескриптора

заголовок

Определяет список. При.этом тип обозначает

списка элементы списка

тип списка, который может быть маркированным, нумерованным или таблицей

<рага> текст

Определяет абзац текста в другом дескрипторе

Документирует параметр, на который указы

пояснение

вает имя параметра. Текст, обозначаемый как пояснение, описывает параметр

Обозначает имя параметра как имя конкретного параметра

Описывает параметр разрешения, связанный с

пояснение

членами класса, на которые указывает идентификатор. Текст, обозначаемый как пояснение, описывает параметры разрешения

Дескриптор

Описание

пояснение

Текст, обозначаемый как пояснение, представляет собой общие комментарии, которые часто используются для описания класса или структуры

пояснение

Текст, обозначаемый как пояснение, описывает значение, возвращаемое методом

Объявляет ссылку на другой элемент, обозначаемый как идентификатор

Объявляет ссылку типа “см. также" на идентификатор

пояснение

Текст, обозначаемый как пояснение, представляет собой общие комментарии, которые часто используются для описания метода или другого члена класса

^<typeparam name = "имя параме

Документирует параметр типа, на который

тра¹^ пояснение

указывает имя параметра. Текст, обозначаемый как пояснение, описывает параметр типа

ctypeparamref name = "имя пара

Обозначает имя параметра как имя пара

метра" />

метра типа

Компилирование документирующих комментариев

Дляполучения XML-файла, содержащего документирующие комментарии, достаточно указать параметр /doc в командной строке компилятора. Например, для компилирования файла DocTest. cs, содержащего XML-комментарии, в командной строке необходимо ввести следующее.

csc DocTest.cs /doc:DocTest.xml