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

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

Документирует параметр, на который указы

пояснение </param>

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

<paramref name = "имя параметра" />

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

<permission cref = "идентификатор">

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

пояснение </permission>

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

Дескриптор

Описание

<remarks> пояснение </remarks>

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

<returns> пояснение </returns>

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

<see cref = "идентификатор" />

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

<seealso cref = "идентификатор" />

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

<sumnjary> пояснение </summary>

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

<typeparam name = "имя параме

Документирует параметр типа, на который

тра1^ пояснение </typeparam>

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

ctypeparamref 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 {

III <summary>

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