ПРИЛОЖЕНИЕ. Краткий справочник по составлению документирующих комментариев
В языке С# предусмотрено три вида комментариев. К двум первым относятся комментарии // и / /, а третий основан на дескрипторах языка 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-файл из интегрированной среды разработки Visual Studio необходимо активизировать окно Свойства (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.