ЯЗЫК ПРОГРАММИРОВАНИЯ С# 2005 И ПЛАТФОРМА .NET 2.0. 3-е издание

Троелсен Эндрю

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

При документировании C#-типов в формате XML первой задачей является выбор одного из двух вариантой нотации: тройной косой черты (///) или признака комментария, который начинается комбинацией косой черты и двух звездочек (/**), а заканчивается – комбинацией звездочки и косой черты (*/). В поле документирующего комментария можно использовать любые XML-элементы, включая элементы рекомендуемого набора, описанные в табл. 4.1.

Таблица 4.1.

Элементы XML рекомендуемые для использования в комментариях к программному коду

XML-элемент документации	Описание
‹с›	Указывает текст, который должен отображаться "шрифтом для программного кода"
‹code›	Указывает множество строк, которое должно рассматриваться, как программный код
<example>	Указывает пример программного кода для описываемого элемента
‹exception›	Документирует возможные исключения данного класса
‹list›	Вставляет список или таблицу в файл документации
‹раrаm›	Описывает данный параметр
‹paramref›	Ассоциирует данный дескриптор XML с параметром
<permission>	Документирует ограничения защиты для данного члена
‹remarks›	Создает описание для данного члена
‹returns›	Документирует возвращаемое значение данного члена
‹see›	Перекрестная ссылка для связанных элементов документа
‹seealso›	Создает раздел '"см. также" в описании
‹summary›	Документирует "поясняющее резюме" для данного члена
‹value›	Документирует данное свойство

В качестве конкретного примера рассмотрим следующее определение типа Car (автомобиль), в котором следует обратить особое внимание на использование элементов ‹summary› и ‹param›.

/// ‹summary›

/// Это тип Car, иллюстрирующий

/// возможности XML-документирования.

/// ‹/summary›

public class Car {

 /// ‹summary›

 /// Есть ли люк в крыше вашего автомобиля?

 /// ‹/summary›

 private bool hasSunroof = false;

 /// ‹summary›

 /// Этот конструктор позволяет установить наличие люка.

 /// ‹/summary›

 /// ‹param name="hasSunroof "› ‹/param›

 public Car(bool hasSunroof) {

this.hasSunroof = hasSunroof;

 }

 /// ‹summary›

 /// Этот метод позволяет открыть люк.

 /// ‹/summary›

 /// ‹param name="state"› ‹/param›

 public void OpenSunroof (bool state) {

if (state == true && hasSunroof == true) Console.WriteLine("Открываем

люк!");

else Console.WriteLine("Извините, у вас нет люка.");

 }

}

Метод Main программы также документируется с использованием XML-элементов.

/// ‹summary›

/// Точка входа приложения.

/// ‹/summary›

static void Main(string [] args) {

 Car с = new Car(true);

 с.OpenSunroof(true);

}

Чтобы на основе комментариев, задающих XML-код, сгенерировать соответствующий файл *.xml, при построении C#-программы с помощью csc.exe используется флаг /doc.

csc /doc:XmlCarDoc.xml *.cs

В Visual Studio 2005 можно указать имя файла с XML-документацией, используя вкладку Build окна свойств (рис. 4.15).

Pис. 4.15. Генерирование файла XML-документации в Visual Studio 2005

Символы форматирования в XML-коде комментариев

Если открыть сгенерированный XML-файл, вы увидите, что элементы будут помечены такими символами, как "M", "T", "F" и т.п. Например:

‹member name = "Т:ХmlDоcCar.Car"›

 ‹summary›

Это тип Car, иллюстрирующий возможности XML-документирования.

 ‹/summary›

‹/member›

В табл. 4.2 описаны значения этих меток.

Таблица 4.2. Символы форматирования XML

Символ форматирования	Описание
E	Элемент обозначает событие
F	Элемент представляет поле
M	Элемент представляет метод (включая конструкторы и перегруженные операции)
N	Элемент определяет пространство имен
P	Элемент представляет свойство типа (включая индексы)
T	Элемент представляет тип (например, класс, интерфейс, структуру, перечень, делегат)

Трансформация XML-кода комментариев

Предыдущие версии Visual Studio 2005 (в частности. Visual Studio .NET 2003) предлагали очень полезный инструмент, позволяющий преобразовать файлы с XML-кодом документации в систему HTML-справки. К сожалению, Visual Studio 2005 не предлагает такой утилиты, оставляя пользователя "один на один" с XML-документом. Если вы имеете опыт использования XML-трансформаций, то, конечно, способны вручную создать подходящие таблицы стилей.

Более простым вариантом является использование инструментов сторонних производителей, которые позволяют переводить XML-код в самые разные форматы. Например, приложение NDoc, уже упоминавшееся в главе 2, позволяет генерировать документацию в нескольких различных форматах. Напомним, что информацию о приложении NDoc можно найти на страницах http://ndoc.sourceforge.net.

Исходный код. Проект XmlDocCar размещен в подкаталоге, соответствующем главе 4.

Резюме

Если вы изучаете .NET, имея опыт работы с любым другим объектно-ориентированным языком программирования, то материал этой главы обеспечит сравнение возможностей используемого вами языка с возможностями языка C#. При отсутствии такого опыта многие представленные в этой главе понятия могут казаться непривычными. Но это не страшно, поскольку по мере освоения оставшегося материала книги вы будете иметь возможность закрепить представленные здесь понятия.