Книга: C# 4.0: полное руководство

ПРИЛОЖЕНИЕ  Краткий справочник по составлению документирующих комментариев

ПРИЛОЖЕНИЕ 

Краткий справочник по составлению документирующих комментариев

В языке C# предусмотрено три вида комментариев. К двум первым относятся комментарии // и /* */, а третий основан на дескрипторах языка XML и называется документирующим комментарием. (Иногда его еще называют XML-комментарием.) Однострочный документирующий комментарий начинается с символов ///, а многострочный начинается с символов /** и оканчивается символами */. Строки после символов /** могут начинаться с одного символа *, хотя это и не обязательно. Если все последующие строки многострочного комментария начинаются с символа *, то этот символ игнорируется.

Документирующие комментарии вводятся перед объявлением таких элементов языка С#, как классы, пространства имен, методы, свойства и события. С помощью документирующих комментариев можно вводить в исходный текст программы сведения о самой программе. При компиляции программы документирующие комментарии к ней могут быть помещены в отдельный XML-файл. Кроме того, документирующие комментарии можно использовать в средстве IntelliSense интегрированной среды разработки Visual Studio.

В С# поддерживаются дескрипторы документации в формате XML, сведенные в табл. 1. Большинство дескрипторов XML-комментариев не требует особых пояснений и действуют подобно всем остальным дескрипторам XML, знакомым многим программистам. Тем не менее дескриптор <list> — сложнее других. Он состоит из двух частей: заголовка и элементов списка. Ниже приведена общая форма дескриптора

<list>:
<listheader>
  <term> имя </term>
  <description> текст </description>
</listheader>

где текст описывает имя. Для описания таблиц текст не используется. Ниже приведена общая форма элемента списка:

<item>
  <term> имя_элемента </term>
  <description> текст </description>
</item>

где текст описывает имя_элемента. Для описания маркированных и нумерованных списков, а также таблиц имя элемента не используется. Допускается применение нескольких элементов списка <item>.

Таблица 1. Дескрипторы XML-комментариев

Дескриптор - Описание

<с> код </с> - Определяет текст, на который указывает код, как программный код

<code> код </code> - Определяет несколько строк текста, на который указывает код, как программный код

<example> пояснение </example> - Определяет текст, на который указывает пояснение, как описание примера кода

<exception cref = "имя"> пояснение </exception> - Описывает исключительную ситуацию, на которую указывает имя

<include file = 'fname' path = 'path[0tagName = "tagID " ] ' /> - Определяет файл, содержащий XML-комментарии для текущего исходного файла. При этом fname обозначает имя файла; path — путь к файлу; tagName — имя дескриптора; tagID — идентификатор дескриптора

<list type = "тип""> заголовок списка элементы списка </list> - Определяет список. При.этом тип обозначает тип списка, который может быть маркированным, нумерованным или таблицей

<рага> текст </para> - Определяет абзац текста в другом дескрипторе

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

<paramref name = "имя параметра" /> - Обозначает имя параметра как имя конкретного параметра

<permission cref = "идентификатор"> пояснение </permission> - Описывает параметр разрешения, связанный с

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

<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-файла.

В приведенном ниже примере демонстрируется применение нескольких документирующих комментариев: как однострочных, так и многострочных. Любопытно, что многие программисты пользуются последовательным рядом однострочных документирующих комментариев вместо многострочных, даже если комментарий занимает насколько строк. Такой подход применяется и в ряде комментариев из данного примера. Его преимущество заключается в том, что он позволяет ясно обозначить каждую строку как часть длинного документирующего комментария. Но это все же, скорее, дело стиля, чем общепринятая практика составления документирующих комментариев.

// Пример составления документирующих комментариев,
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.
  ///</param>
  ///<see cref = "int" > </ see >
  /// < returns >
  /// Сумма возвращается в виде значения типа int.
  ///</returns>
  /// </summary>
  static int Summation(int val) {
    int result = 0;
    for (int i = 1; i <= val; i++)
      result += i;
    return result;
  }
}

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

csc XmlTest.cs /doc:XmlTest.xml

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

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Program</name>
    </assembly>
    <members>
        <member name="T:Test">
            <remark>
            Это пример многострочного документирования в формате XML.
            В классе Test демонстрируется ряд дескрипторов.
            </remark>
        </member>
        <member name="M:Test.Main">
            <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.

Оглавление книги