Читать «C# 4.0: полное руководство» онлайн - страница 671

членами класса, на которые указывает идентификатор. Текст, обозначаемый как пояснение, описывает параметры разрешения

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

<returns> пояснение </returns> - Текст, обозначаемый как пояснение, описывает значение, возвращаемое методом

<see cref = "идентификатор" /> - Объявляет ссылку на другой элемент, обозначаемый как идентификатор

<seealso cref = "идентификатор" /> - Объявляет ссылку типа “см. также" на идентификатор

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

<typeparam name = "имя параметра"> пояснение </typeparam> - Документирует параметр типа, на который указывает имя параметра. Текст, обозначаемый как пояснение, описывает параметр типа

<typeparamref 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 {
  ///<summary>
  /// Выполнение программы начинается с метода Main().
  ///</summary>
  static void Main() {
    int sum;
    sum = Summation(5);
    Console.WriteLine("Сумма последовательных чисел " +
    5 + " равна " + sum);
  }
  ///<summary>
  /// Метод Summation() возвращает сумму его аргументов.
  ///<param name = "val" >
  /// Суммируемое значение передается в качестве параметра val.