ПРИЛОЖЕНИЕ. Краткий справочник по составлению документирующих комментариев
В языке С# предусмотрено три вида комментариев.К двум первым относятся комментарии // и / /,а третий основан на дескрипторах языка XML и называется документирующим комментарием. (Иногда его ещеназывают XML-комментарием.) Однострочный документирующий комментарий начинается с символов ///, а многострочный начинается с символов / и оканчивается символами */. Строки после символов / могут начинатьсяс одного символа , хотя это и не обязательно. Если все последующие строки многострочного комментария начинаются с символа , то этот символ игнорируется.Документирующие комментарии вводятся перед объявлением таких элементов языка С#, как классы, пространстваимен, методы, свойства и события. С помощью документирующих комментариев можно вводить в исходный текстпрограммы сведения о самой программе. При компиляции программы документирующие комментарии к неймогут быть помещены в отдельный XML-файл. Кроме того,документирующие комментарии можно использоватьв средстве IntelliSense интегрированной среды разработкиVisual Studio.Дескрипторы XML-комментариев
В С# поддерживаются дескрипторы документациив формате XML, сведенные в табл. 1. Большинство дескрипторов XML-комментариев не требует особых пояснений1040 Часть II. Библиотека C#и действуют подобно всем остальным дескрипторам XML, знакомым многим программистам. Тем не менее дескриптор — сложнее других. Он состоит из двухчастей: заголовка и элементов списка. Ниже приведена общая форма дескриптора
:
имя
текст где текст описывает имя. Для описания таблиц текст не используется. Ниже приведена общая форма элемента списка:
имя_элемента
текст где текст описывает имяэлемента. Для описания маркированных и нумерованныхсписков, а также таблиц имяэлемента не используется. Допускается применение нескольких элементов списка .Таблица 1. Дескрипторы XML-комментариевДескриптор Описание<с> код </с> Определяет текст, на который указывает код,как программный код код Определяет несколько строк текста, на который указывает код, как программный код
пояснение Определяет текст, на который указывает пояснение, как описание примера кода
пояснение Описывает исключительную ситуацию, на которую указывает имя
Определяет файл, содержащий XML-kom-ментарии для текущего исходного файла. Приэтом fname обозначает имя файла; path —путь к файлу; tagName — имя дескриптора;tagID — идентификатор дескриптора
<list type = "тип""> заголовоксписка элементы списка Определяет список. При этом тип обозначаеттип списка, который может быть маркированным, нумерованным или таблицей<раrа> текст Определяет абзац текста в другом дескрипторе
пояснение Документирует параметр, на который указывает имя_параметра. Текст, обозначаемыйкак пояснение, описывает параметр
Обозначает имя_параметра как имя конкретного параметра
пояснение Описывает параметр разрешения, связанный счленами класса, на которые указывает идентификатор. Текст, обозначаемый как пояснение, описывает параметры разрешенияОкончание табл. 1Компилирование документирующих комментариевДля получения XML-файла, содержащего документирующие комментарии, достаточно указать параметр /doc в командной строке компилятора. Например, длякомпилирования файла DocTest.cs, содержащего XML-комментарии, в команднойстроке необходимо ввести следующее.csc DocTest.cs /doc:DocTest.xmlДля вывода результата в XML-файл из интегрированной среды разработки VisualStudio необходимо активизировать окно Свойства (Properties) для текущего проекта.Затем следует выбрать свойство Построение (Build), установить флажок XML-файлдокументации (XML Documentation File) и указать имя выходного XML-файла.Пример составления документации в формате XMLВ приведенном ниже примере демонстрируется применение нескольких документирующих комментариев: как однострочных, так и многострочных. Любопытно, чтомногие программисты пользуются последовательным рядом однострочных документирующих комментариев вместо многострочных, даже если комментарий занимает насколько строк. Такой подход применяется и в ряде комментариев из данного примера.Его преимущество заключается в том, что он позволяет ясно обозначить каждую строкукак часть длинного документирующего комментария. Но это все же, скорее, дело стиля,чем общепринятая практика составления документирующих комментариев.Дескриптор Описание
пояснение Текст, обозначаемый как пояснение, представляет собой общие комментарии, которыечасто используются для описания класса илиструктуры
пояснение Текст, обозначаемый как пояснение, описывает значение, возвращаемое методом
Объявляет ссылку на другой элемент, обозначаемый как идентификатор
Объявляет ссылку типа “см. также” на идентификатор
пояснение Текст, обозначаемый как пояснение, представляет собой общие комментарии, которыечасто используются для описания метода илидругого члена класса
пояснение Документирует параметр типа, на которыйуказывает имя_параметра. Текст, обозначаемый как пояснение, описывает параметр типа
Обозначает имя_параметра как имя параметра типа1042 Часть II. Библиотека C#// Пример составления документирующих комментариев.using System;/* Это пример многострочного документирования в формате XML.В классе Test демонстрируется ряд дескрипторов./class Test {/// /// Выполнение программы начинается с метода Main()./// static void Main() {int sum;sum = Summation(5);Console.WriteLine("Сумма последовательных чисел " +5 + " равна " + sum);}/// /// Метод Summation() возвращает сумму его аргументов./// /// Суммируемое значение передается в качестве параметра val./// /// /// /// Сумма возвращается в виде значения типа int./// /// static int Summation(int val) {int result = 0;for(int i=l; i <= val; i++)result += i;return result;}}Если текст приведенной выше программы содержится в файле XmlTest.cs, то последующей команде будет скомпилирована программа и получен файл XmlTest.xml,содержащий комментарии к ней.csc XmlTest.cs /doc:XmlTest.xmlПосле компилирования получается XML-файл, содержимое которого приведенониже.<?xml version="l.0"?>
DocTest
Это пример многострочного документирования в формате XML.В классе Test демонстрируется ряд дескрипторов.
Выполнение программы начинается с метода Main().
Метод Summation() возвращает сумму его аргументов.
Суммируемое значение передается в качестве параметра val.
Сумма возвращается в виде значения типа int.Следует заметить, что каждому документируемому элементу присваивается уникальный идентификатор. Такие идентификаторы применяются в других программах,которые документируются в формате XML.
