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

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

Дескриптор

Описание

<���с> код </с>

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

код

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

пояснение

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

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

пояснение

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

1fname 1path =

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

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

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

этом 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

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

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

/**

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

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

*/

class Test {

III

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

Ill static void Main() { int sum;

sum = Summation(5) ;

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

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

}

III

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

Ill

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

Ill

III

III

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

Ill

III

static int Summation(int val) { int result = 0;

for(int i=l; i <= val; i++) result += i;

return result;

}

}

Если текст приведенной выше программы содержится в файле Xml Test. cs, то по следующей команде будет скомпилирована программа и получен файл Xml Test. xml, содержащий комментарии к ней.