Язык программирования С# 2005 и платформа .NET 2.0.

Документирование исходного кода в C# с помощью XML

В завершение этой главы мы рассмотрим специфические для C# лексемы комментариев, которые порождают документацию программного кода на. базе XML. Если вы имеете опыт программирования на языке Java, то, скорее всего, знаете об утилите javadoc. Используя javadoc, можно превратить исходный вод Java в соответствующее HTML-представление. Модель документирования, принятая в C#, оказывается немного иной в том отношении, что процесс преобразования комментариев в XML является заботой компилятора (при использовании опции /doc), а не особой утилиты.

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

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

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

XML-элемент документации	Описание
‹с›	Указывает текст, который должен отображаться "шрифтом для программного кода"
‹code›	Указывает множество строк, которое должно рассматриваться, как программный код
	Указывает пример программного кода для описываемого элемента
‹exception›	Документирует возможные исключения данного класса
‹list›	Вставляет список или таблицу в файл документации
‹раrаm›	Описывает данный параметр
‹paramref›	Ассоциирует данный дескриптор XML с параметром
	Документирует ограничения защиты для данного члена
‹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);