Sandcastle - генерируем документацию

В предыдущей статье, я рассказал о возможностях XML-документации и привел простой пример XML-документирования исходного кода, теперь пора научиться получать заветную документацию в удобном для чтения виде, разумеется, генерировать документацию будем автоматическими средствами Sandcastle.

Для начала, создадим новый проект и добавим в него, заготовленный в предыдущей статье, исходный код, после чего соберем проект с флагом /doc:XMLDoc.xml (или Visual Studio в свойствах проекта "Properties -> Build -> Output" ставим галочку "XML documentation file". После успешной сборки проекта, в выходной папке будет находиться файл XML-документации следующего содержания:

<?xml version="1.0"?>

<doc>

    <assembly>

        <name>CommentTest</name>

    </assembly>

    <members>

        <member name="M:XMLCommentTest.Program.Factorial(System.Int32)">

            <summary>

            <para>

            Вычисляет факториал числа.

            </para>

            </summary>       

            <param name="number">Неотрицательное число.</param>

            <exception cref="T:System.ArgumentOutOfRangeException">

            Если <paramref name="number"/> отрицательное число.

            </exception>

            <exception cref="T:System.OverflowException">

            Если значение факториала слишком велико для типа <see cref="T:System.Decimal"/>.

            </exception>

            <returns>Значение факториала.</returns>

            <example>Простой пример, для <see cref="M:XMLCommentTest.Program.Factorial(System.Int32)"/>.

            <code>

            class Program

            {

                static void Main(string[] args)

                {

                    Console.WriteLine(Factorial(5));

                }

            }

            </code>

            </example>

            <seealso cref="T:System.Math"/>      

            <remarks>

            Вычисление факториала для больших значений <paramref name="number"/>

            может быстро привести к переполнению.

            </remarks>       

        </member>

    </members>

</doc>

Заметьте, что любое упоминание типа или члена происходит полным именем [Имя пространства имен].[Имя типа или члена], хотя явно мы этого не указывали:

cref="T:System.ArgumentOutOfRangeException"

name="M:XMLCommentTest.Program.Factorial(System.Int32)"

На данном этапе мы получили XML-документацю проекта, осталось перегнать ее в формат, удобный для чтения. Конечно, мы можем сами написать свой XSLT для отображения нашей документации в любом виде. Классическая задача XML+XSLT

Но в нашем случае, это стандартная задача, для которой можно обойтись стандартными средствами. На сегодняшний день существуют несколько бесплатных систем автоматического получения технической документации: Sandcastle, NDoc и другие, но безусловным лидером является Sandcastle. Его и рассмотрим.

Если коротко о Sandcastle, то можно сказать что он генерирует готовый CHM-файл с полной навигацией (как локальной так и с ссылками на внешний MSDN), разделами и фильтрами поиска по документации для указанной сборки/xml-документации (более подробно о возможностях можно узнать здесь).
Устанавливается Sandcastle с помощью install-файла, скачать который можно с официального сайта. Я советую также скачать GUI-надстройку Sandcastle Help File Builder.

Приступаем к работе, устанавливаем скаченный софт в следующем порядке: сначала Sandcastle далее Sandcastle Help File Builder, после чего проверьте(echo %DXROOT%) переменную окружения DXROOT, в ней должен находиться путь к Sandcastle. Далее открываем Sandcastle Help File Builder, и видим, что окно Sandcastle Help File Builder состоит из двух областей: Project Properties и Project Explorer. Добавляем в окне "Project Explorer" путь к нашей сборке/xml-документации, тем самым указав сборку, для которой будем генерировать документацию. Процесс генерации можно настроить, для этого в окне "Project Properties" содержатся следующие разделы:

1. Build - отвечает за сборку: формат документации, версия .net, лог-файл и другие.
2. Comments - общие комментарии.
3. Help file - настраивает содержимое документации: копирайт, footer/header-ы, заголовки, стиль представления, ссылки и прочие.
4. Path - задает рабочие пути: выходная директория, директория Sandcastle и другие.
5. Show Missing Tag - показывать ли предупреждение, если пропущен документирующий тэг.
6. Visibility - задает фильтр того, что попадет в документацию.

Выставив необходимых свойства, сохраните файл проекта (*.shfbproj) и запустите Build (через меню или комбинацией клавиш "CTRL-SHIFT-B"). Если Вы все правильно сделали, то в выходной директории (по-умолчению это .\Help\) увидите собранный файл документации (по-умолчанию Documentation.chm) и лог файл. Документация готова!

Дополнение:
Q: "А как же диаграммы классов? Можно ли их встраивать в документацию?"
A: "Да, можно! Например, использовать компонент Drawbridge"