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

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

В завершение этой главы мы рассмотрим специфические для 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);

Перейти на страницу:

Похожие книги

1С: Бухгалтерия 8 с нуля
1С: Бухгалтерия 8 с нуля

Книга содержит полное описание приемов и методов работы с программой 1С:Бухгалтерия 8. Рассматривается автоматизация всех основных участков бухгалтерии: учет наличных и безналичных денежных средств, основных средств и НМА, прихода и расхода товарно-материальных ценностей, зарплаты, производства. Описано, как вводить исходные данные, заполнять справочники и каталоги, работать с первичными документами, проводить их по учету, формировать разнообразные отчеты, выводить данные на печать, настраивать программу и использовать ее сервисные функции. Каждый урок содержит подробное описание рассматриваемой темы с детальным разбором и иллюстрированием всех этапов.Для широкого круга пользователей.

Алексей Анатольевич Гладкий

Программирование, программы, базы данных / Программное обеспечение / Бухучет и аудит / Финансы и бизнес / Книги по IT / Словари и Энциклопедии
1С: Управление торговлей 8.2
1С: Управление торговлей 8.2

Современные торговые предприятия предлагают своим клиентам широчайший ассортимент товаров, который исчисляется тысячами и десятками тысяч наименований. Причем многие позиции могут реализовываться на разных условиях: предоплата, отсрочка платежи, скидка, наценка, объем партии, и т.д. Клиенты зачастую делятся на категории – VIP-клиент, обычный клиент, постоянный клиент, мелкооптовый клиент, и т.д. Товарные позиции могут комплектоваться и разукомплектовываться, многие товары подлежат обязательной сертификации и гигиеническим исследованиям, некондиционные позиции необходимо списывать, на складах периодически должна проводиться инвентаризация, каждая компания должна иметь свою маркетинговую политику и т.д., вообщем – современное торговое предприятие представляет живой организм, находящийся в постоянном движении.Очевидно, что вся эта кипучая деятельность требует автоматизации. Для решения этой задачи существуют специальные программные средства, и в этой книге мы познакомим вам с самым популярным продуктом, предназначенным для автоматизации деятельности торгового предприятия – «1С Управление торговлей», которое реализовано на новейшей технологической платформе версии 1С 8.2.

Алексей Анатольевич Гладкий

Финансы / Программирование, программы, базы данных