Эндрю Троелсен - ЯЗЫК ПРОГРАММИРОВАНИЯ С# 2005 И ПЛАТФОРМА .NET 2.0. 3-е издание
Замечание. После рассмотрения Windows Forms и ASP.NET вы поймете, что в Visual Studio 2005 ключевое слово partial используется для разделения программного кода, генерируемого инструментами разработки. Используя этот подход, вы можете сосредоточиться на поиске подходящих решений и не заботиться об автоматически генерируемом программном коде.
Документирование исходного кода в 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› Указывает множество строк, которое должно рассматриваться, как программный код <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#. При отсутствии такого опыта многие представленные в этой главе понятия могут казаться непривычными. Но это не страшно, поскольку по мере освоения оставшегося материала книги вы будете иметь возможность закрепить представленные здесь понятия.
Эта глава началась с обсуждения принципов ООП: инкапсуляции, наследования и полиморфизма. Сервис инкапсуляции можно обеспечить с помощью традиционных методов чтения/модификации, свойств типа или открытых полей, доступных только для чтения. Наследование в C# реализуется еще проще, поскольку этот язык не имеет для наследования специального ключевого слова, а предлагает использовать операцию, обозначаемую двоеточием. Наконец, для поддержки полиморфизма в C# предлагается использовать ключевые слова abstract, virtual, override и new.
