FAQ по документирующим комментариям в C#

Автор: Anson Horton
Источник: http://blogs.msdn.com/ansonh/archive/2006/09/11/750056.aspx

С тех пор как мы выпустили самую первую версию C# 1.0, я получаю один-два вопроса в месяц о документирующих XML-комментариях. Для краткости такие комментарии часто называют «doc comments». Диапазон вопросов — от использования XML-комментариев в Visual Studio до рекомендуемой XML-схемы. Этот пост рассматривает несколько общих вопросов из тех что я видел.

Почему нет многострочного варианта XML-комментариев?

На самом деле, есть две формы документирующих комментариев в C#, одно- и многострочная. Однако, однострочная версия используется намного чаще; фактически, многострочная версия не поддерживалась до компилятора версии 1.1, хотя она и была определена в спецификации языка на версии 1.0. Однострочная версия, по-видимому, привычна любому пользователю Visual Studio; синтаксическим признаком является тройной слэш в начале строки (///):

        /// <summary>
        /// This is the single line version of the doc comment
        /// </summary>
        static void Example()
        {
        }

Многострочная версия использует /**:

        /** <summary>
         * This is the multi-line version
         * </summary> */
        static void Example()
        {
        }

Они функционально идентичны, единственное различие состоит в том что многострочную версию можно использовать прямо в строке («inline»), внутри выражений.

Сервис языка C# не поддерживает многострочные XML-комментарии настолько, насколько это сделано для однострочных комментариев (т.е., при вводе /** не происходит автоматической генерации тэгов); однако, подсветка многострочных документирующих комментариев работает, и в VS2005 есть возможность получения списка завершения для тэгов, но вы должны сначала закрыть многострочный комментарий, а затем вернуться назад чтобы вводить тэги.

Как мне сделать так, чтобы VS показывала текст XML-комментариев на типы и методы моих компонентов в списках завершения и в браузере объектов?

Довольно долгое время этот вопрос был наиболее частым. И краткий, и полный ответ состоит в том, что вы должны распространять XML-файл, созданный компилятором, вместе с компонентом. Они должны лежать в одном и том же каталоге, и имя XML-файла должно совпадать с именем компонента, за исключением расширения «.xml». Для демонстрации этого я написал руководство, содержащее последовательность действий (для VS2003), оно доступно здесь.

Как в документирующих XML-комментариях ссылаться на дженерик-типы (generic types)?

Некоторые из тэгов, рекомендованных для C#, имеют атрибут с именем «cref», означающий «code reference». Этот атрибут может использоваться инструментами для создания ссылок между различными типами и членами (например, браузер объектов использует cref-ы для создания гиперссылок, позволяющих быстро переходить к связанному типу). На самом деле, компилятор C# до некоторой степени понимает cref. Компилятор пытается связать тип или член, указанный в атрибуте cref, с элементом кода, определяющим источник. В случае, когда это удается, этот тип/член полностью называется в генерируемом XML-файле. Например:

using System.Collections;


class Program
{
    /// <summary>
    /// DoSomething takes a <see cref="ArrayList"/>
    /// </summary>
    void DoSomething(ArrayList al) { }
}

Это преобразуется в следующий фрагмент XML-файла:

        <member name="M:Program.DoSomething(System.Collections.ArrayList)">
            <summary>
            DoSomething takes a <see cref="T:System.Collections.ArrayList"/>
            </summary>
        </member>

Обратите внимание, что компилятор связал ArrayList и подставил вместо него System.Collections.ArrayList.

Я уверен, вы говорите — «ух ты, отлично... но что нам это дает в плане дженериков?» Хороший вопрос. Дженерики усложняют документирующие комментарии, потому что C# использует угловые скобки, которые обычно обозначают тэги XML. Есть возможность использовать обычный механизм экранирования угловых скобок в XML (< >). К сожалению, при этом текст выглядит довольно уродливо:

using System.Collections.Generic;


class Program
{
    /// <summary>
    /// DoSomething takes a <see cref="List&lt;T>"/>
    /// </summary>
    void DoSomething(List<int> al) { }
}

Этот способ может стать довольно обременительным, в случае когда дженерик-тип имеет множество аргументов. Команда разработки компилятора решила эту проблему, разрешив использование альтернативного синтаксиса для ссылок на дженерик-типы и их методы в документирующих комментариях. А именно, вместо использования открывающих и закрывающих угловых скобок, допустимо использовать открывающие и закрывающие фигурные скобки:

using System.Collections.Generic;


class Program
{
    /// <summary>
    /// DoSomething takes a <see cref="List{T}"/>
    /// </summary>
    void DoSomething(List<int> al) { }
}

Компилятор понимает такой синтаксис и корректно заменит List{T} на System.Collections.Generic.List<T>.

Если используется тэг <example>, в котором показан пример со множеством дженерик-типов и методов, то более простым способом будет окружить пример блоком CDATA. В этом случае нет необходимости в экранировании угловых скобок.

Какие тэги документирующих комментариев понимаются и используются Visual Studio?

Набор тэгов, которые Visual Studio использует для обработки и представления информации:

Имя тэга	Инструменты, использующие тэг
summary	Completion lists, quick info, class view, class designer, object browser, object test bench
param	Parameter help, quick info, object test bench, class designer, object browser
exception	Completion lists, quick info, object browser
include	Компилятор C#
returns	Object browser
see/seealso	Object browser

Функция «метаданные в качестве исходного кода» («metadata as a source»), которая применяется при выполнении команды Go To Definition с переходом на тип или член класса, определенный в метаданных, обрабатывает ряд тэгов, определенных в спецификации C# и пытается с их использованием представить метаданные в приемлемом виде.

Как из XML-файла получить документацию в формате HTML или .chm?

На самом деле, генерируемый XML не содержит достаточно информации для полной генерации хорошей документации. Фактически, прямой целью было лишь создание XML-файла, содержащего информацию, достаточную для комментирования элементов кода, представленных в метаданных. Тем не менее, есть ряд инструментов, принимающих на входе сборку и XML-файл, и генерирующих красивый и удобный для изучения документ. NDoc был излюбленным средством, по словам многих разработчиков, с которыми я говорил. Но я вижу, что разработка NDoc довольно замедлилась; другим вариантом является использование SandCastle.

Перевод: Никита Зимин,
ведущий разработчик компании «Деловые программы»

Вернуться к списку статей