</doc>

В каталоге XSLTStyledXMLDocumentation вы найдете также версию файла DocumentedClasses .xml, включающую в себя эту директиву. Пример результата показан на рис. 3L10.

DocumentedClasses.Garden

CKis repfMtrtwg a garden, ana the contents of that qvOmn.

Uta he W.iJtflCivj.rj.j matnoa o add contanrt wrnch must nent frer

One* contarts have baan added tha garden can ba v su4k ad ui4ig the itlPLWj niathod. Suitat)** ciaiiai fof addig nclude

: a tkxeer, iit* IkI

Repretentt a buih. sm г a Repretentt a (pnnkler, su

Its a itatue. wca lul a t>ef>ch. sua 5x2

If a flower to tha n-

I (..iriJcnf Int:)2,Vni:}V) с oiistajctor Constructor lhat sets dpmarsons of the 0 rii n object

PoremitlHn

to object (Site on y-ai-rt)

Puc. 31.10. Стилизация XML-документации

Стмевое оформление не идеально - в частности, элементы <seealso> отображаются неправильно и, как видно из снимка экрана, существуют проблемы с форматированием элемента <code>, - но в целом результат достаточно впечатляет. Файлы служат прекрасной отправной точкой при создании Web-страницы документации. Особенно удачен способ связывания элементов <see> с точками привязки на странице.

Стилевое оформление XML-документации с помощью XSLT

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

На этом этапе мы хотели бы сослаться на настоящего мастера С# - Андерса Хейлсберга (Anders Hejlsberg). Он опубликовал документ XSLT и связанный с ним файл CSS, предназначенные для преобразования файлов XML-документации в стилизованный HTML-текст. Эти два файла, doc.xsl и doc.ess, можно найти в загружаемом коде данной главы в каталоге XSLTStyledXMLDocumentation. Чтобы использовать эти файлы, просто добавьте директиву обработки в свои файлы XML-документации:

<?xml version= 1.0 ?>

<?xml:stylesheet href= doc.xsl type= text/xsl ?>

<doc>

Вероятно, наибольшая проблема, связанная с этим подходом, состоит в том, что вся информация отображается на одной HTML-странице, которая может оказаться очень большой.

Средства документирования

Другой способ обработки XML-документации - использования специального средства. До недавнего времени наиболее совершенным средством стилевого оформления XML-документации была программа NDoc. Она представляет собой инструментальное средство от независимых разработчиков, позволяющее преобразовывать документацию в ряд форматов, в том числе в справочные файлы в стиле MSDN. К сожалению, разработка NDoc застопорилась (на момент написания этой книги).

Для получения последней версии (бесплатной) NDoc обратитесь на сайт http:/ / ndoc.sourceforge.net. Хотя она и не модернизировалась в течение некоторого времени, программа остается работоспособной (при использовании каркаса .NET Framework версии Lx). Не исключено, что в будущем проект получит новую жизнь, поэтому время от времени стоит заглядывать на этот сайт. Пример NDoc-документа-ции, форматированной в стиле справки, показан на рис. 3L1L

fwv Loc r Вас*

О Q Л Л

Stop R ih Н trm Jp .r4

C a repeienting a ga-deo and the coirtentt e# that garden. Tof a kit of a membet ot th t trpe. %вв UStlASILlcSSX

G Oer\Cort .. method

inGaiCh <ra<hod Garden Gatfar. melted Garden flefrovamemod

GaidenConlerl XPoi (иореЛу Geidfri eHrt YPoi piopeoy G-ih-nrtrwj

Gaidentau GelPUr TiaAod

Gardarctati

GedenConiert dau

GederConlert Ощ0> oooerty GaidwiConlert Geiflar -nemod GedenConieol PWi (xooerty

Thrrad Safpty

PubUc .tatK (Shaded in Vitual Ba ) rrembert Ы th.j type are t *e к rr.uWheeded Opefa(<Dn< ln tance membert we not gu ra i eed to be thread-ta*e

Ute the ids method to add cofltont*. which muit lenertt from uaffleCafitont On< oontentt лв е been added the gard*n can b vitua i *d u ng fhi Suabie datiet for adding ndude

that

Bap i t a По-* Bepfetentf a tree nze R*prot nt< a buih. site Rec#e ent a (prwibter. Pepreiend a atatua, м RapfetarXi a Ьапсл f.i

The ollow.ng coda add* a f4)war to tft m.ddl of a garden

toid.n .r<.r u> Ou<Un(ll. 11>.

e>r<l . Addlna* riovailt. ill.

Requiramentt

Nameapacai Lu<aj>Ti iiltJCIatttt

Attemblr; Docum fMdCla * (m DocumanttdClei e dll) Sac Alao

Puc. 31.11. Пример NDoc-дакуменшаиии

В случае возможного окончательного исчезновения NDoc стоит обратить внимание на альтернативное средство - Sandcastle. Компания Microsoft использует этот инструмент для генерирования документации по API, поэтому не приходится удивляться, что оно предоставляет все функциональные возможности, которые от него можно ожидать. Оно полностью поддерживает последнюю версию .NET Framework и функциональные возможности языка С#, в том числе, например, обобщения, не поддерживаемые программой NDoc.

Однако поскольку Sandcastle, по сути, представляет собой внутреипсч- ( jx к ни его использование - не самая простая задача. Для него существует псч ко ii.i.c> (.I I большинство из которых были созданы его пользователями.

Более подробную информацию об этом программном средетмс мо/кно ii.m ти на сайте www.sandcastledocs.com или http: blogs.msdn.com/:I Пользующийся популярностью GUI для Sandcastle можно также загр\.ип1, и \ < .т и www.codeplex.com/SHFB.

Резюме

В этой главе мы рассмотрели все аспекты XML-документации - от сс с олд.ши! и > возможного применения. В этой главе рассмотрены следующие вопрос ы.

□ Синтаксис XML-документации.

□ Способы включения внешней XML-документации.

□ Способы использования XML-документации в средствах IntelliSense и ()1)(ч i Browser среды Visual Studio.

□ Использование диаграмм классов для добавления XML-докумен гаппп

□ Способы генерирования файлов XML-документации.

□ Способы обработки файлов XML-документации в коде С#.

□ Способы стилевого оформления XML-документации с помощью XSL1

□ Способы применения таких программных средств, как NDoc и Sandc .isik , л 1я построения справочных файлов из XML-документации.

Честно говоря, добавление XML-документации в проекты может окаллп.с я лт i.i точно трудоемким процессом и придавать исходному коду несколько лапу чаи m.iii lui i, Но в крупномасштабных проектах документирование - важная часть процсч с а ралра ботки, и результат полностью оправдывает затраченные усилия - особен по при и( пользовании средств, разработанных для этой цели.

Упражнения

1. Какие из следующих элементов можно использовать в ХМЬ-докумеи гацпи?

<summary>

<usage>

<member>

<seealso>

<typeparamref>

2. Какие дескрипторы XML-документации верхнего уровня слсдус! ис по.п.ижа11. для документирования свойства?

3. XML-документация содержится в файлах исходного кода (#. K()j)pc кгпо дли )i() утверждение?

4. Каков основной недостаток добавления XML-документации посрсдс njom дна граммы классов?

5. Что необходимо сделать, чтобы обеспечить возможность Hcnojn.ionainni дрх- и ми проектами XML-документации, содержащейся в библиотеках клас с ои?