Feel Good.

22 марта 2010

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. На практике бывает очень полезно знать, какие исключения можно ожидать при выполнении метода или при обращении к свойству. И еще, при комментировании кода не забывайте, что только полезный комментарий считается комментарием.

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


Progg it

5 комментариев:

  1. C XML комментариями есть множество нюансов. В Вашем примере XML комментарии занимают куда больший объем строк, нежели сам код, а ведь это еще не полная документация - не хватает примеров использования.

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

    GhostDoc вещь неудобная, особенно если пишешь документацию на русском. Поправить GhostDoc исходный код не удалось, т.к. сборки GhostDoc подписаны.

    Отмечу, что можно создать процесс нормального документирования, но не "из коробки", а затратив порядочно времени на внедрение - для этого пришлось детально поизучать Sandcastle Help File Builder - его некоторые надстройки (теги , , вынос примеров кода во внешние файлы) оказались очень удобны; сделать перевод базового шаблона на русский язык; написать AddIn для Visual Studio для быстрой вставки перекрестных ссылок и освоить MAML (по которому не особо много документации) для того чтобы писать что-то помимо API Reference и т.д.

    Думаю, есть способы по-проще решать такие задачи...

    Хотя, считаю правилом хорошего тона писать хотя бы summary и описание параметров - отдача от них очень ощутима.

    ОтветитьУдалить
  2. @dipyalov
    1. Это всего лишь демонстрационный пример.
    2. Насчет GhostDoc, у меня версия 2.5.09166 для VS2008, работает нормально и с русскими строками. В чем неудобство?
    3. Согласен, можно применить и не "из коробки", но решение из "из коробки" покрывает большинство потребностей при документировании кода и самое главное, оно экономит время.
    4. Здесь я с Вами полностью согласен, summary должен быть обязательным.

    Спасибо за развернутый комментарий и за наводку про MAML, не знал.

    ОтветитьУдалить
  3. Спасибо за статью.

    Вот мой способ: http://msug.vn.ua/blogs/akrakovetsky/archive/2010/01/22/generating-code-documentation.aspx

    ОтветитьУдалить
  4. Пытался недавно найти возможность писать в code xml, не знаете как?

    ОтветитьУдалить
  5. @outcoldman
    Можно использовать, блок CDATA
    (http://msdn.microsoft.com/en-us/library/ms256076.aspx)

    ОтветитьУдалить