1. Комментарии к документации

C# предоставляет программистам механизм документирования своего кода с помощью специального синтаксиса комментариев с XML-текстом. Комментарии в файлах исходного кода, имеющие определенный вид, могут быть использованы для управления инструментом создания XML из этих комментариев и элементов исходного кода, которым они предшествуют. Комментарии, использующие такой синтаксис, называются комментариями к документации. ///" \t "See documentation comment"Они должны непосредственно предшествовать пользовательскому типу (такому как класс, делегат или интерфейс) или члену (такому как поле, событие, свойство или метод). Инструмент создания XML называется генератором документации (таким генератором может быть, но не обязан, сам компилятор C#.) Производимый генератором документации вывод называется файлом документации. Файл документации используется в качестве входных данных для средства просмотра документации, инструмента для создания отображения сведений о типе и сопутствующей документации.

Эта спецификация предлагает набор тегов для использования в комментариях к документации, но использование этих тегов не является обязательным, можно при желании использовать другие теги, если соблюдаются правила правильного XML.

1. Введение

Комментарии, имеющие специальный вид, могут быть использованы для управления инструментом создания XML из этих комментариев и элементов исходного кода, которым они предшествуют. Такие комментарии являются однострочными комментариями, начинающимися с трех косых черт (///), или комментариями с разделителями, начинающимися с косой черты и двух звездочек (/**). Они должны непосредственно предшествовать пользовательскому типу (такому как класс, делегат или интерфейс) или члену (такому как поле, событие, свойство или метод), который они комментируют. Разделы атрибутов (§17.2) считаются частью объявлений, так что комментарии к документации должны предшествовать атрибутам, примененным к типу или члену.

Синтаксис:

однострочный_комментарий_к_документации: /// символы_ввода_необ

комментарий_с_разделителями_к_документации: /** текст_комментария_с_разделителями_{необязательно} */

Если в однострочном_комментарии_к_документации символ пустого_пространства следует за символами /// в каждом из однострочных_комментариев_к_документации, примыкающих к текущему однострочному_комментарию_к_документации, то этот символ пустого_пространства не включается в XML-вывод.

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

Пример:

/// <summary>Class <c>Point</c> models a point in a two-dimensional /// plane.</summary> /// public class Point { /// <summary>method <c>draw</c> renders the point.</summary> void draw() {…} }

Текст в комментариях к документации должен быть правильным согласно правилам XML (http://www.w3.org/TR/REC-xml). При неправильном XML создается предупреждение и файл документации будет содержать комментарий, сообщающий об ошибке.

Хотя разработчики могут создавать свои собственные наборы тегов, рекомендуемый набор определен в §Error: Reference source not found. Некоторые из рекомендуемых тегов имеют специальные значения.

• тег <param> используется для описания параметров. Если используется этот тег, генератор документации должен проверить, что указанный параметр существует и что все параметры описаны в комментариях к документации. Если проверка неуспешна, генератор документации выдает предупреждение;

• атрибут cref можно привязать к любому тегу для создания ссылки на элемент кода. Генератор документации должен проверить, что этот элемент кода существует. Если проверка неуспешна, генератор документации выдает предупреждение. При поиске имени, описанного в атрибуте cref, генератор документации должен принимать во внимание видимость пространства имен в соответствии с операторами using, встречающимися в исходном коде. Для общих элементов кода нельзя использовать обычный универсальный синтаксис (т. е. "List<T>"), так как он создает неправильный XML. Можно использовать фигурные скобки вместо угловых (т. е. List{T}) или escape-синтаксис XML (т. е. List<T>);

• тег <summary> предназначен для использования средством просмотра документации для отображения дополнительных сведений о типе или члене;

• тег <include> включает сведения из внешнего XML-файла.

Внимательно отнеситесь к тому, что файл документации не предоставляет полные сведения о типе и членах (например, он не содержит никакие сведения о типе). Для получения таких сведений о типе или члене файл документации необходимо использовать в сочетании с соображениями по фактическому типу или члену.