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

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

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