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

Длявывода результата в 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;

}

}

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

csc XmlTest.cs /doc:XmlTest.xml

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

DocTest

cmember name=^ffT:Test^ff>

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

lfM: Test .Main¹¹ >

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

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

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

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

Следует заметить, что каждому документируемому элементу присваивается уникальный идентификатор. Такие идентификаторы применяются в других программах, которые документируются в формате XML.

Предметный указатель

А

Аксессоры вызов304