Сообщений 0 
Оценка 149 
Оценить 
| Сообщений 0 Оценка 149 Оценить
|
С тех пор как мы выпустили самую первую версию C# 1.0, я получаю один-два вопроса в месяц о документирующих XML-комментариях. Для краткости такие комментарии часто называют «doc comments». Диапазон вопросов — от использования XML-комментариев в Visual Studio до рекомендуемой 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 есть возможность получения списка завершения для тэгов, но вы должны сначала закрыть многострочный комментарий, а затем вернуться назад, чтобы вводить тэги.
Довольно долгое время этот вопрос был наиболее частым. И краткий, и полный ответ состоит в том, что вы должны распространять XML-файл, созданный компилятором, вместе с компонентом. Они должны лежать в одном и том же каталоге, и имя XML-файла должно совпадать с именем компонента, за исключением расширения «.xml». Для демонстрации этого я написал руководство, содержащее последовательность действий (для VS2003), оно доступно здесь.
Некоторые из тэгов, рекомендованных для 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<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 использует для обработки и представления информации:
| Имя тэга | Инструменты, использующие тэг |
|---|---|
| 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 не содержит достаточно информации для полной генерации хорошей документации. Фактически, прямой целью было лишь создание XML-файла, содержащего информацию, достаточную для комментирования элементов кода, представленных в метаданных. Тем не менее, есть ряд инструментов, принимающих на входе сборку и XML-файл, и генерирующих красивый и удобный для изучения документ. NDoc был излюбленным средством, по словам многих разработчиков, с которыми я говорил, но я вижу, что разработка NDoc довольно замедлилась. Другим вариантом является использование SandCastle.
| Сообщений 0 Оценка 149 Оценить
|