Герберт Шилдт - C# 4.0: полное руководство

:

имя

текст

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

имя_элемента

текст

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

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

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

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

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

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

пояснение -Описывает исключительную ситуацию, на которую указывает имя

-Определяет файл, содержащий XML-комментарии для текущего исходного файла. При этом fname обозначает имя файла; path — путь к файлу; tagName — имя дескриптора; tagID — идентификатор дескриптора

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

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

пояснение -Документирует параметр, на который указывает имя параметра. Текст, обозначаемый как пояснение, описывает параметр

-Обозначает имя параметра как имя конкретного параметра

пояснение -Описывает параметр разрешения, связанный с

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

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

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

-Объявляет ссылку на другой элемент, обозначаемый как идентификатор

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

пояснение -Документирует параметр типа, на который указывает имя параметра. Текст, обозначаемый как пояснение, описывает параметр типа

-Обозначает имя параметра как имя параметра типа

Для получения XML-файла, содержащего документирующие комментарии, достаточно указать параметр /doc в командной строке компилятора. Например, для компилирования файла DocTest.cs, содержащего XML-комментарии, в командной строке необходимо ввести следующее.

csc DocTest.cs /doc:DocTest.xml

Для вывода результата в XML-файл из интегрированной среды разработки Visual Studio необходимо активизировать окно Свойства(Properties) для текущего проекта. Затем следует выбрать свойство Построение(Build), установить флажок XML-файл документации(XML Documentation File) и указать имя выходного XML-файла.

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

// Пример составления документирующих комментариев,

using System;

/**

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

В классе Test демонстрируется ряд дескрипторов.

*/

class Test {

///

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

///

static void Main() {

int sum;

sum = Summation(5);

Console.WriteLine("Сумма последовательных чисел " +

5 + " равна " + sum);

}

///

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

///

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

///

/// </ see >

/// < returns >

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

///

///

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-файл, содержимое которого приведено ниже.

Program

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

В классе Test демонстрируется ряд дескрипторов.

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

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

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

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

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

(Удален. Все-равно номеров страниц нет. См. Оригинал)

HERBERT SCHILDT ПОЛНОЕ РУКОВОДСТВО C# 4.0

Москва • Санкт-Петербург • Киев 2011

ББК 32.973.26-018.2.75 Ш 57 УДК 681.3.07

Издательский дом "Вильямс"

Зав. редакцией С.Н. Тригуб Перевод с английского и редакция И.В. Берштейна

По общим вопросам обращайтесь в Издательский дом "Вильямс" по адресу: info@williamspublishing.com, http://www.williamspublishing.com

Шилдт, Герберт.

Ш57 C# 4.0: полное руководство. : Пер. с англ. — М. : ООО "И.Д. Вильямс", 2011. — 1056 с.: ил. — Парал. тит. англ.