Обозначает имя параметра как имя пара
метра" />
метра типа
Компилирование документирующих комментариев
Для получения 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:Testff>
<remark>
Это пример многострочного документирования в формате XML. В классе Test демонстрируется ряд дескрипторов.
</remark>
</member>
<member name=lfM: Test .Main11 >
<summary>
Выполнение программы начинается с метода Main(). </summary>
</member>
<member name="M:Test.Summation(System.Int32)">
<summary>
Метод Summation() возвращает сумму его аргументов.
<param name="val">
Суммируемое значение передается в качестве параметра val. </param>
<see cref=”T:System.Int32"> </see>
<returns>
Сумма возвращается в виде значения типа int.
</returns>
</summary>
</member>
</members>
</doc>
Следует заметить, что каждому документируемому элементу присваивается уникальный идентификатор. Такие идентификаторы применяются в других программах, которые документируются в формате XML.
Предметный указатель
А
Аксессоры вызов 304
модификаторы доступа ограничения 323 применение 320 назначение 304 разновидности 304 событий 500 Анонимные функции назначение 483 преимущество 483 разновидности 483 Аргументы именованные назначение 252 применение 252 командной строки 255 метода 162 назначение 52 необязательные назначение 247 и неоднозначность 250 и перегрузка методов 249 порядок объявления 249 способы передачи методу 220 типа 579 Атрибуты AttributeUsage 570 Conditional 571