Читаем C# 4.0: полное руководство полностью

В языке C# предусмотрено три вида комментариев. К двум первым относятся комментарии // и /* */, а третий основан на дескрипторах языка XML и называется документирующим комментарием. (Иногда его еще называют XML-комментарием.) Однострочный документирующий комментарий начинается с символов ///, а многострочный начинается с символов /** и оканчивается символами */. Строки после символов /** могут начинаться с одного символа *, хотя это и не обязательно. Если все последующие строки многострочного комментария начинаются с символа *, то этот символ игнорируется.

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

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

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

:

  имя

  текст

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

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

  текст

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

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

Дескриптор - Описание

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

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

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

пояснение - Описывает исключительную ситуацию, на которую указывает имя

- Определяет файл, содержащий XML-комментарии для текущего исходного файла. При этом fname обозначает имя файла; path — путь к файлу; tagName — имя дескриптора; tagID — идентификатор дескриптора

заголовок списка элементы списка - Определяет список. При.этом тип обозначает тип списка, который может быть маркированным, нумерованным или таблицей

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

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

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

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

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

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

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

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

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

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

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

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

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

csc DocTest.cs /doc:DocTest.xml

Для вывода результата в XML-файл из интегрированной среды разработки Visual Studio необходимо активизировать окно Свойства (Properties) для текущего проекта. Затем следует выбрать свойство Построение (Build), установить флажок XML-файл документации (XML Documentation File) и указать имя выходного XML-файла.

Пример составления документации в формате XML