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

 // Конструкторы.
public MyClass {}
 // Открытые члены.
 public void MemberA {}
 public void MemberB {}
 }
}
// MyClass_Private.cs
namespace PartialTypes {
 public partial class MyClass {
 // Приватные поля данных.
private string someStringData;
 // Приватные вспомогательные члены.
 public static void SomeStaticHelper{}
 }
}

Это, в частности, упростит задачу изучения открытого интерфейса типа для новых членов команды разработчиков. Вместо изучения единого (и большого) файла C# с целью поиска соответствующих членов, разработчики получают возможность рассмотреть только открытые члены. Конечно, после компиляции этих файлов с помощью csc.exe в результате все равно получается единый унифицированный тип (рис. 4.14).

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

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

Замечание. После рассмотрения 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" и т.п. Например: