компиляции программы документирующие комментарии к ней могут быть помещены в отдельный XML-файл. Кроме того, документирующие комментарии можно использовать в средстве IntelliSense интегрированной среды разработки Visual Studio.
где текст описывает имя. Для описания таблиц текст не используется. Ниже приведена общая форма элемента списка:
<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 = "имя параметра" /> - Обозначает имя параметра как имя параметра типа
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-комментариев
В С# поддерживаются дескрипторы документации в формате 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-файла.
Пример составления документации в формате 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> Это пример многострочного документирования в формате