/ <param name= museMood >

/ Значение перечисления <see cre£= MuseMood /> укаэьтает настроение музы. / </param>

Атрибут name элемента <param> или <typeparam> не только указывает имя параметра, но и будет соответствовать атрибуту name любых элементов <paramref> или <typeparamref >, ссылающихся на данный параметр.

<returns> и <value>

Эти два элемента аналогичны в том, что они оба связаны с возвращаемым значением: <returns> применяется для возвращаемого значения методов, а <value> - для значения свойства, которое также можно считать возвращаемым значением. Ни один из этих элементов не использует никаких атрибутов. Применительно к методам элемент <returns> можно использовать следующим образом:

/ <summary>

/ Метод, используемый для добавления музы.

/ </summary>

/ <param name= museName >

/ Параметр <see langword= string /> указывает имя музы. / </param>

/ <param name= museMood >

/ Значение перечисления <see cref= MuseMood /> указывает настроение музы. / </param> / <returns>

/ Возвращаемое значение этого метода - <see langword= void />. / </returns>

Пример использования элемента <value> применительно к свойствам выглядит следующим образом:

/ <summary>

/ Свойство для получения или установки музы. / </summary> / <value>

/ Тип этого свойства - <see langword= string />. / </value>

<permission>

Этот элемент используют для описания разрешений, связанных с целевым объектом. Фактическая установка разрешений выполняется другими средствами, такими как применение атрибута к методу; элемент <permission> просто позволяет информировать других пользователей об этих разрешениях.

Элемент <permission> включает в себя атрибут cref, поэтому, при желании, можно реализовать ссылку на класс, содержащий дополнительную информацию, такой как System. Security. PermissionSet. Например:

/ <permission cref= System.Security.PermissionSet > / Только администраторы могут использовать этот метод. / </permission>

<exception>

Этот элемент используют для описания любых исключений, которые могут генерироваться во время использования целевого объекта. Он имеет атрибут cref, который можно применять для перекрестных ссылок на тип исключения. Например, этот элемент можно было бы использовать для указания диапазона допустимых значений свойства и описания последствий попытки установки недопустимого значения:

/ <exception cref= System.ArgumentException >

/ Это исключение будет порождаться при установке <paramref name= Width /> / равным отрицательному значению. / </exception>

<seealso>

Как было отмечено ранее, элемент <seealso> применяется в качестве элемента верхнего уровня. Можно использовать несколько таких элементов, которые, в зависимости от применяемого инстументального средства, могут быть форматированы в виде списка ссылок в конце записи целевого объекта:

/ <summary>

/ Это краткое описание класса MyPoet class. / </summary>

/ <seealso cref= MyParchment /> / <seealso cref= MyTheme /> / <seealso cref= MyToenails />

<include>

Включение большого объема XML-документации в исходные файлы может приводить к некоторой путанице, поэтому стоит подумать о ее помещении в отдельные файлы. Например, такой подход может быть желательным, если кто-то другой готовит документацию для кода, поскольку этому лицу не нужно предоставлять доступ к самим исходным файлам.

Элемент <include> позволяет решать эту задачу посредством двух своих атрибутов file и path. Атрибут file указывает внешний XML-файл, содержащий XML-документацию, которую нужно включить, а path служит для отыскания конкретного раздела XML-кода внутри документа с помощью синтаксиса XPath.

Например, ссылку на внешнюю XML-документацию можно было бы реализовать следующим образом:

/ <include file= ExternalDoc.xml path= doc\imentation/classes/MyClass/* /> public class MyClass

В этом примере реализована ссылка на файл ExternalDoc. xml. Он может содержать код, подобный показанному ниже:

<?xml version= l.О encoding= utf-8 ?> <documentation> <classes> <MyClass> <suminary>

Краткая информация во внешнем файле. </summary> <remarks>

Замечательно, не правда ли? </remarks> </MyClass> </classes> </documentation>

В свою очередь, этот код мог бы быть эквивалентным следующему: / <summary>

/ Краткая информация во внешнем файле. / </summary> / <remarks>

/ Замечательно, не правда ли? / </remarks>

public class MyClass

Добавление XML-документации

с использованием диаграммы классов

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

Вспомните, что диаграммы классов доступны только в Visual Studio и не входят в состав Visual Studio Express. Для ознакомления с этим примером требуется наличие установленной среды Visual Studio.

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

Доступные возможности демонстрируются в следующем практическом занятии.

Практическое зшнятт] Добавление ХМL-документации

в диаграмму класса

1. Создайте новое приложение библиотеки классов DiagrammaticDocumentation и сохраните его в каталоге С: \BegVCSharp\Chapter31.

2. После загрузки проекта щелкните на кнопке View Class Diagram (Просмотр диаграммы класса) в окне Solution Explorer. Должна открыться диаграмма, содержащая класс Class 1, автоматически сгенерированный при создании приложения библиотеки классов.

3. Добавьте класс DocumentedClass и измените его члены в соответствии с рис. 3L3 и табл. 31.2.

Puc. 31.3. Добавление класса DocumentedClass