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

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

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

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

этом 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 = "имя параме

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

тра¹^ пояснение </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>

Это пример многострочного документирования в формате XML.

В классе Test демонстрируется ряд дескрипторов.

</remark>

*/

class Test {

III <summary>

III Выполнение программы начинается с метода Main.

Ill </summary> static void Main { int sum;

sum = Summation(5) ;

Console.WriteLine("Сумма последовательных чисел " +

5 + " равна " + sum);

}

III <summary>

III Метод Summation возвращает сумму его аргументов.

Ill <param name = "val">

III Суммируемое значение передается в качестве параметра val.

Ill </param>

III <see cref="int"> </see>

III <returns>

III Сумма возвращается в виде значения типа int.