Нужно всего лишь установить флажок XML Documentation File (Файл XML-документации) и указать имя выходного файла. В общем случае целесообразно сохранять файл XML-документации в каталоге самой сборки, поскольку именно здесь IDE ищет его. Если клиентское приложение обращается к документированной сборке в другом решении, преимущества применения IntelliSense и Object Browser доступны, только если IDE может обнаружить файл XML-документации.

Как только настройки компоновки, связанные с XML-документацией, будут включены, компилятор окажется сконфигурированным для активного поиска XML-документации в классах. Хотя отсутствие XML-документации для конкретного класса или метода не обязательно является ошибкой, IDE будет предупреждать обо всех отсутствующих компонентах в форме предупреждений в окне Error List (Список ошибок). Пример такого предупреждения показан на рис. 31.6.

Puc. 31.6. Пример предупреждения об отсутствии XML-комментария для класса С las si

Это предупреждение, сгенерированное предыдущим примером, указывает на отсутствие документации для класса Class 1 (который мы оставили без изменений).

Файл XML-документации, созданный для приведенного примера, имеет следующий вид:

<?xml version= l.0 ?> <doc>

<assembly>

<name>DiagrammaticDocumentation</name>

</assembly>

<members>

<member name= T:DiagrammaticDocumentation.DocumentedClass > <summary>

Этот класс позволяет разлагать числа на множители в соответствии

с определенными правилами.

</summary>

<гетагкз>Используйте метод GetFactor() для разложения числа на множители в соответствии с правилами,

определенными свойствами IncludeOne и IncludeSelf.</remarks> </member>

<member name= M:DiagrammaticDocumentation.DocumentedClass.GetFactors > <summary>

Извлекает множители числа.

</summary>

<remarks>

Этот метод служит для получения множителей числа - т.е. всех

чисел, на которые число может быть разделено без остатка.

Если оба значения IncludeOne и IncludeSelf равны true, и возвращенный

результат состоит только из двух чисел (самого числа и единицы),

число является простым.

</remarks>

<returns>Boзвpaщaeт массив long.</returns> </member>

<member name= P:DiagrammaticDocumentation.DocumentedClass.IncludeOne > <summary>

Включает 1 в результат работы метода GetFactors (). </summary>

<remarks>Ecли значение этого свойства установлено равным true, результат

long[] метода GetFactors () будет содержать единицу.</remarks> <уа1ие>3начение типа bool.</value> </member>

<member name= P:DiagrammaticDocumentation.DocumentedClass.IncludeSelf > <summary>

Включает себя в результат работы метода GetFactors(). </summary>

<remarks>Ecли значение этого свойства установлено равным true, результат long[] метода GetFactors() будет содержать его параметр numberToFactor. </remarks>

<уа1ие>3начение типа bool.</value> </member> </members> </doc

Этот документ содержит перечисленные ниже элементы.

□ Элемент <doc> корневого уровня, содержащий всю остальную информацию документации.

□ Элемент <assembly>, содержащий элемент <name>, который хранит имя сборки, описываемой XML-документацией.

□ Элемент <members>, содержащий XML-документацию каждого из членов сборки.

□ Несколько элементов <member>, каждый из которых содержит атрибут name, указывающий, к какому типу или члену применяется содержащаяся в нем XML-документация.

Атрибуты name элементов <member> соответствуют единой схеме именования. Все они - имена, принадлежащие одному из следующих пространств имен - т.е. они все начинаются с одной из следующих букв:

□ Т - указывает, что член является типом (классом, интерфейсом, распоркой (strut), перечислением или делегатом);

□ М - указывает, что член является методом;

□ Р - указывает, что член является свойством или индексатором;

□ F - указывает, что тип является полем или членом перечисления (этот вариант не нашел своего отражения в примере);

□ Е - указывает, что тип является событием (этот вариант не нашел своего отражения в примере).

Любые ошибки в XML-документации типа отображаются в сгенерированном файле в виде закомментированного элемента <member>:

<!- Badly formed XML comment ignored for member T:DiagrammaticDocumentation.DocumentedClass ->

<!- Неправильно сформированный XML-комментарий игнорируется для члена Т:DiagrammaticDocumentation.DocumentedClass ->

Внутри элемента <member> XML-документация целевого объекта вставляется в том виде, каком она существует (если только не возникает какаяо проблема с XML-кодом).

Пример приложения, оснащенного XML-документацией

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

Классы, включенные в состав библиотеки DocumentedClasses, показаны на рис. 31.7.

ф УРО

31Г Dtpth

! 3

j ЗГ XPei

I Mtthodf

1 ♦ GirdtoCott

i GttPt*n

MMrKtClMi

AbitnctCUii

UWtty

CiMi

Pfoptrtitj i V4t№0dt

Mtttiodi ♦ Buih

Ргорвгйв

Pi*n

Mtdods

♦ Tr..

Mtmodt Btnch

* Proptrses

r PI--

я Mt№ods ♦ Spry*%f

Pwc. 31,7. Классы, вклтсченные в состав библиотеки DocumentedClasses

Основная идея этой библиотеки классов в том, что клиентское приложение может создавать экземпляр класса Garden (Сад), а затем добавлять в сад экземпляры классов, производных от GardenContent. Это можно использовать для получения простого графического представления сада. По существу классы образуют инструмент разработки очень обобщенного сада.

На тот случай, если вы решите самостоятельно исследовать код, загружаемый код для данной главы содержит эту библиотеку классов, но его наличие вовсе не обязательно. Загружаемый код содержит также простое клиентское приложение DocumentedClassesClient, код которого имеет следующий вид:

static void Main(string[] args) {

int gardenWidth = 40; int gardenDepth = 20;

Garden zoyGarden = new Garden (gardenWidth, gardenDepth) ;

zoyGarden. Add (new Bench (4, 2)) ; myGarden.Add(new Bench(10, 2)); nyGarden. Add (new Sprinkler (20, 10)); zoyGarden. Add (new Tree(3, 13)) ; zoyGarden. Add (new Tree (25, 7)); royGarden.Add(new Tree(35, 15));