ПРИЛОЖЕНИЕ Краткий справочник по составлению документирующих комментариев

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

Документирующие комментарии вводятся перед объявлением таких элементов языка С#, как классы, пространства имен, методы, свойства и события. С помощью документирующих комментариев можно вводить в исходный текст программы сведения о самой программе. При компиляции программы документирующие комментарии к ней могут быть помещены в отдельный 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 = 'имя параметра'>

 

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

 

пояснение </param>

 

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

 

<paramref name = "имя параметра" />

 

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

 

<permission cref = "идентификатор">

 

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

 

пояснение </permission>

 

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

 

Дескриптор

 

Описание

 

<remarks> пояснение </remarks>

 

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

 

<returns> пояснение </returns>

 

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

 

<see cref = "идентификатор" />

 

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

 

<seealso cref = "идентификатор" />

 

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

 

<sumnjary> пояснение </summary>

 

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

 

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

 

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

 

тра1^ пояснение </typeparam>

 

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

 

ctypeparamref name = "имя пара

 

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

 

метра" />

 

метра типа

 

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

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

csc DocTest.cs /doc:DocTest.xml

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

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

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

// Пример составления документирующих комментариев, using System;

/** <remark>