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

Шилдт Герберт

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

<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.

Ill </returns>

III </summary>

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, содержащий комментарии к ней.

csc XmlTest.cs /doc:XmlTest.xml

После компилирования получается XML-файл, содержимое которого приведено ниже.

<?xml version="l.0"?>

<doc>

<assembly>

<name>DocTest</name>

</assembly>

<members>

cmember name=^ffT:Test^ff>