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

Рис. 4.14. После компиляции парциальные типы уже не будут парциальными

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

Замечание. После рассмотрения Windows Forms и ASP.NET вы поймете, что в Visual Studio 2005 ключевое слово partial используется для разделения программного кода, генерируемого инструментами разработки. Используя этот подход, вы можете сосредоточиться на поиске подходящих решений и не заботиться об автоматически генерируемом программном коде.

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

В качестве конкретного примера рассмотрим следующее определение типа 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›

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