XML-документация

Когда вы программируете, помните, что код пишется людьми для людей, а компилятор проглотит любой синтаксически правильный код. Согласитесь, что код с комментариями намного проще понять, а библиотеку с документацией намного удобнее использовать. Представьте ситуацию, перед Вами поставлена задача: поддерживать техническую документацию проекта в актуальном состоянии. Подумав, вы понимаете, что поддерживать её вручную с ростом проекта будет все сложнее и сложнее, поэтому приходите выводу, что оптимальным решением будет использовать автоматические средства генерации документации, но для этого, Ваши комментарии должны быть представлены так, чтобы их было бы удобно обрабатывать(только не надо изобретать велосипеды)... XML!

А вот это уже интересно. Только представьте себе, вся документация представлена XML файлом, а ее представление в виде XSLT шаблона. Захотели новое представление, создали новый XSLT шаблон. Итак, мы вплотную подошли к понятию, как XML-документация. XML-документация, это документация, описываемая языком XML. XML-документирование кода подразумевает запись всех комментариев в формате XML. Формат записи комментариев стандартен, поэтому любой такой комментарий успешно разбирается различными IDE (intellisense) или автоматическими средствами документирования (Sandcastle, NDoc и другие). Любой комментарий XML-документации, задается тэгами, которые, в свою очередь, можно разделить на три группы в порядке важности: описывающие, уточняющие и форматирующие.

Описывающие тэги, как наиболее важная группа. Именно эти тэги использует в подсказках intellisense IDE:

• summary - описание типа или члена типа.
• param - описание входных параметров метода.
• returns - описание возвращаемого значения метода.
• exception - указание возможных исключений.
• example - пример использования.
• remarks - дополнительная информация.
• seealso - ссылка на "смотри также".
• include - ссылка на комментарий в другом файле.
• permission - описание доступа.

Уточняющие тэги, данный тип тэгов дополняет группу описывающих тэгов:

• see - ссылка на член или поле.
• paramref- ссылка на параметр.
• typeparamref - ссылка на тип в generic типах.
• typeparam - описание generic типа.
• value - описывает представляемое свойством значение.

Форматирующие тэги, служат только для форматирования текста в документации:

• para - помечает блок текста как параграф.
• code - помечает блок текста как код.
• list - помечает блок текста как список/таблица.

Все XML-комментарии начинаются с тройного слэша (///), при этом первые два слэша указывают компилятору игнорировать текст, следующий после, а третий слэш - что это XML-комментарий. Если вы используете Visual Studio, то при тройном нажатии на / Visual Studio автоматически вставит комментарий с несколькими XML тэгами. Приведу простой пример документирования метода класса с помощью XML, для этого я добавлю статический метод, который вычисляет факториал своего аргумента:

/// <summary>

/// <para>

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

/// </para>

/// </summary>       

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

/// <exception cref="ArgumentOutOfRangeException">

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

/// </exception>

/// <exception cref="OverflowException">

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

/// </exception>

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

/// <example>Простой пример, для <see cref="Factorial(int)"/>.

/// <code>

/// class Program

/// {

///     static void Main(string[] args)

///     {

///         Console.WriteLine(Factorial(5));

///     }

/// }

/// </code>

/// </example>

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

/// <remarks>

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

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

/// </remarks>

public static decimal Factorial(int number)

{

    if (number < 0)

        throw new ArgumentOutOfRangeException

                ("number", "Аргумент должен быть положительным.");

 

    decimal result = number;

    for (int next = 2; next < number; next++)

    {

        result *= next;

    }

    return result;

}

После чего, попробуйте набрать в Visual Studio код, указанный ниже, и вы увидите, что при наборе кода, Intellisense будет подсказывать нам информацию о методе Factorial, записанную в нашем XML-комментарии.

static void Main(string[] args)

{

    decimal result = Factorial(5);

}

Кстати, отмечу удобный плагин для Visual Studio, называется GhostDoc, он позволяет генерировать комментарии автоматически.

Добавлю, что многие зря игнорируют тэг exception. На практике бывает очень полезно знать, какие исключения можно ожидать при выполнении метода или при обращении к свойству. И еще, при комментировании кода не забывайте, что только полезный комментарий считается комментарием.

Читать продолжение