Объектно-ориентированное программирование.-6

В получаемом XML-файле все элементы кода имеют некоторые правила представления. Во-первых, при упоминании элемента кода используется полное иерархическое представление пространств имен. Например, если мы использовали тип String, то его представление в XML будет иметь вид System.String, точнее – T:System.String, т.к. перед каждым элементом кода в XML ставится модификатор типа элемента (табл. 5.6).

Допустимые теги перечислены в табл. 5.7.

Примечания: (*) – синтаксис тега проверяется компилятором.

Угловые скобки считаются частью кода XML, поэтому если их необходимо использовать в качестве текста или значения параметра, используются мнемокоды «<» и «>». Можно использовать и некоторые другие мнемокоды языка HTML. Для вставки символа с указанным кодом используется мнемокод «<код>;». Например, мнемокод для неразрывного пробела –

« ».

Пример:

namespace XMLDocumentationSample

{

///<summary>

///Главный класс программы <c>Program</c>.

///</summary>

///<permission cref="System.Security.PermissionSet">

///Доступ к классу не ограничен.</permission>

public class Program

{

///<summary>

///<para>Метод <c>Mul2</c> возвращает результат умножения

///аргументов <paramref name="a"/> и

///<paramref name="b"/>.</para>

///<para>Существует также версия для трех аргументов

432

///(<see cref="Mul3"/>).</para>

///</summary>

///<param name="a">Первый множитель.</param>

///<param name="b">Второй множитель.</param>

///<returns>Результат умножения

///<paramref name="a"/>*<paramref name="b"/>.</returns>

///<exception cref="OverflowException">Если результат

///умножения <paramref name="a"/> и <paramref name="b"/>

///приводит к переполнению.</exception>

///<example><para>Пример использования:</para>

///<code>

///int a = 5, b = 5, c;

///try

///{

///    c = Program.Mul2(a, b);

///}

///catch(OverflowException)

///{

///    Console.WriteLine("Результат

///умножения приводит к переполнению");

///}

///</code>

///</example>

///<permission cref="System.Security.PermissionSet">

///Доступ к методу не ограничен.</permission>

///<seealso cref="System.Exception"/>

///<seealso cref="System.Int32"/>

public static int Mul2(int a, int b)

{

return checked(a * b);

}

///<summary>

///<para>Метод <c>Mul3</c> возвращает результат умножения

///аргументов <paramref name="a"/>, <paramref name="b"/>

///и <paramref name="c"/>.</para>

///<para>Существует также версия для двух аргументов

///(<see cref="Mul2"/>).</para>

///</summary>

///<param name="a">Первый множитель.</param>

///<param name="b">Второй множитель.</param>

///<param name="c">Третий множитель.</param>

///<returns>Результат умножения <paramref name="a"/>*

///<paramref name="b"/>*<paramref name="c"/>.</returns>

///<exception cref="OverflowException">Если результат

///умножения <paramref name="a"/>, <paramref name="b"/>

///и <paramref name="c"/> приводит к переполнению.

///</exception>

///<example><para>Пример использования:</para>

///<code>

///int a = 5, b = 5, c = 5, d;

///try

///{

///    d = Program.Mul3(a, b, c);

///}

///catch(OverflowException)

///{

///    Console.WriteLine("Результат

///умножения приводит к переполнению");

///}

433

///</code>

///</example>

///<permission cref="System.Security.PermissionSet">

///Доступ к методу не ограничен.</permission>

///<seealso cref="System.Exception"/>

///<seealso cref="System.Int32"/>

public static int Mul3(int a, int b, int c)

{

return checked(a * b * c);

}

///<summary>

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

///</summary>

///<param name="args">Аргументы командной строки.</param>

///<returns>Код возврата приложения:

///<list type="table">

///<listheader>

///<term>Код</term>

///<term>Описание</term>

///</listheader>

///<item>

///<term>0</term>

///<term>Успешное завершение приложения</term>

///</item>

///<item>

///<term>1</term>

///<term>Приложение завершено с ошибкой</term>

///</item>

///</list>

///</returns>

static int Main(string[] args)

{

try

{

Console.WriteLine(Mul2(5, 5)); Console.WriteLine(Mul3(5, 5, 5));

}

catch

{

return 1;

}

return 0;

}

}

}

В результате работы программы генерируется следующий код XML:

<?xml version="1.0"?> <doc>

<assembly> <name>5_6_2_xml</name>

</assembly>

<members>

<member name="T:XMLDocumentationSample.Program"> <summary>

Главный класс программы <c>Program</c>.

</summary>

434

<permission cref="T:System.Security.PermissionSet">Доступ к классу не ограничен.</permission>

</member>

<member

name="M:XMLDocumentationSample.Program.Mul2(System.Int32,System.Int32)">

<summary>

<para>Метод <c>Mul2</c> возвращает результат умножения

аргументов

<paramref name="a"/> и <paramref name="b"/>.</para> <para>Существует также версия для трех аргументов (<see

cref="M:XMLDocumentationSample.Program.Mul3(System.Int32,System.Int32,System. Int32)"/>).</para>

</summary>

<param name="a">Первый множитель.</param> <param name="b">Второй множитель.</param>

<returns>Результат умножения <paramref name="a"/>*<paramref name="b"/>.</returns>

<exception cref="T:System.OverflowException">Если результат умножения <paramref name="a"/> и

<paramref name="b"/> приводит к переполнению.</exception> <example><para>Пример использования:</para>

<code>

int a = 5, b = 5, c; try

{

c = Program.Mul2(a, b);

}

catch(OverflowException)

{

Console.WriteLine("Результат умножения приводит к

переполнению");

}

</code>

</example>

<permission cref="T:System.Security.PermissionSet">Доступ к методу не ограничен.</permission>

<seealso cref="T:System.Exception"/> <seealso cref="T:System.Int32"/>

</member>

<member

name="M:XMLDocumentationSample.Program.Mul3(System.Int32,System.Int32,System.

Int32)">

<summary>

<para>Метод <c>Mul3</c> возвращает результат умножения

аргументов

<paramref name="a"/>, <paramref name="b"/> и <paramref name="c"/>.</para>

<para>Существует также версия для двух аргументов (<see cref="M:XMLDocumentationSample.Program.Mul2(System.Int32,System.Int32)"/>).</ para>

</summary>

<param name="a">Первый множитель.</param> <param name="b">Второй множитель.</param> <param name="c">Третий множитель.</param>

<returns>Результат умножения <paramref name="a"/>*<paramref name="b"/>*<paramref name="c"/>.</returns>

<exception cref="T:System.OverflowException">Если результат умножения <paramref name="a"/>,

<paramref name="b"/> и <paramref name="c"/> приводит к переполнению.</exception>

435

<example><para>Пример использования:</para>

<code>

int a = 5, b = 5, c = 5, d; try

{

d = Program.Mul3(a, b, c);

}

catch(OverflowException)

{

Console.WriteLine("Результат умножения приводит к

переполнению");

}

</code>

</example>

<permission cref="T:System.Security.PermissionSet">Доступ к методу не ограничен.</permission>

<seealso cref="T:System.Exception"/> <seealso cref="T:System.Int32"/>

</member>

<member

name="M:XMLDocumentationSample.Program.Main(System.String[])">

<summary>

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

</summary>

<param name="args">Аргументы командной строки.</param> <returns>Код возврата приложения:

<list type="table"> <listheader>

<term>Код</term> <term>Описание</term>

</listheader>

<item>

<term>0</term>

<term>Успешное завершение приложения</term> </item>

<item>

<term>1</term>

<term>Приложение завершено с ошибкой</term> </item>

</list>

</returns>

</member>

</members>

</doc>

5.6.2.2. Генерация документации

Далее можно полученный код XML преобразовать в документацию любого формата. В ранних версиях Visual Studio был встроенный инструмент для преобразования XML в HTML. В настоящее время можно использовать внешние инструменты. Например, утилиту NDoc (сайт ndoc.sourceforge.net). К учебнику прилагается дистрибутив этой утилиты версии 1.3.1 (размер дистрибутива – около 2,7 Мб). К сожалению, ее развитие остановилось на версии .NET 1.1. Если проект использует более старшую версию .NET, восполь-

436

зоваться этой утилитой не удастся.

До появления .NET, корпорация Microsoft для создания файлов справки распространяла утилиту HTML Help Workshop. Полученные с ее помощью файлы формата CHM (Microsoft Compiled/Compressed HTML) содержат набор HTML-страниц с перекрестными ссылками и дополнительные ресурсы (такие, как картинки). Также существует возможность создания оглавления, организации поиска по индексу и т.д. Также существует HTML Help API для интеграции файла справки CHM с приложением (открытие справки на нужной странице, привязка визуальных элементов управления программы к контексту справки и т.п.).

В настоящее время для получения файлов CHM в среде .NET используется утилита Microsoft Sandcastle. Для ее использования необходимо установить собственно генератор документации Sandcastle (свежая версия доступна на сайте sandcastle.codeplex.com, к учебнику прилагается дистрибутив версии 2.6 за июнь 2010 года, 15 Мб) и визуальную среду разработки Sandcastle Help File Builder (shfb.codeplex.com, к учебнику прилагается дистрибутив версии 1.9.1.0, 9 Мб). В отличие от многих сторонних утилит, Sandcastle умеет работать с отражением, и извлекает из сборок .NET всю необходимую для документирования информацию. Кроме того, документация может быть сохранена не только в формате HTML Help, но и в формате МSHelp 2, а также в виде набора страниц HTML (статических и с динамическим поиском).

Итак, установим на ПК Sandcastle и SHFB. Создадим в папке проекта «5_6_2_xml» подпапку «html». Запустим утилиту SHFB, для удобства можно (подобно тому, как это было сделано в п. 2.3.6) добавить в меню «Сервис» среды разработки Visual Studio дополнительный пункт для запуска SHFB, исполняемый файл утилиты по умолчанию имеет спецификацию

<папка Program Files>\EWSoftware\Sandcastle Help File

Builder\SandcastleBuilderGUI.exe

Создадим в SHFB новый проект (пункт меню «File» → «New Project», соответствующая кнопка на панели инструментов или комбинация клавиш Ctrl+N), сохраним его в ранее созданной папке «html» с любым именем. После этого в правой части окна появится панель «Project Explorer». В контекстном меню для пункта «Documentation Source» выберем единственный пункт «Add Documentation Source…» (рис. 5.3).

437

Рис. 5.3 – Создание документации в утилите SHFB

В появившемся диалоге открытия файла выберем исполняемый файл сборки «5_6_2_xml.exe». При этом автоматически сформируется XML-файл и также добавится в источники документации. После этого на странице «Project Properties» можно установить опции проекта. Выберем формат документации «HelpFileFormat = Website» (чтобы HTML-файлы не собирались в один CHM файл, а были доступны по отдельности) и язык «Language = Русский (Россия)». Все, документацию можно генерировать (пункт меню «Documentation» → «Build Project», соответствующая кнопка на панели инструментов или комбинация клавиш Ctrl+Shift+B). После этого в папке «html» появится подпапка «Help» со всеми файлами документации. Для просмотра выберите файл «Index.html» (рис. 5.4).

438

Рис. 5.4 – Готовая документация

5.6.2.3. Использование XML-кода в IntelliSense

Кроме того, XML-документацией может пользоваться среда разработки Visual Studio, используя технологию IntelliSense. При использовании документированных типов и членов информация из документации появляется во всплывающей подсказке (рис. 5.3).

439

Рис. 5.5 – Использование документации по методу класса

Также появляется всплывающая подсказка по параметрам документированного метода (рис. 5.4).

Рис. 5.6 – Использование документации по параметрам метода

440