Рекомендуемые XML-теги для комментариев к документации по C#

В комментариях к документации по C# используются XML-элементы, что позволяет определить структуру выходной документации. Одним из последствий использования этой функции является то, что в комментарии к документации можно добавить любой допустимый XML-код. Компилятор C# копирует эти элементы в выходной XML-файл. Несмотря на то что в комментариях (включая любой допустимый HTML-элемент) можно использовать любой допустимый XML-код, документирование кода рекомендуется по многим причинам.

Далее приводится ряд рекомендаций, распространенные сценарии использования и вопросы, которые нужно иметь в виду при работе с тегами XML-документации в коде C#. Несмотря на то что теги можно поместить в комментарии к документации, в этой статье описываются рекомендуемые теги для наиболее распространенных конструкций языка. Во всех случаях следует соблюдать следующие рекомендации:

  • Для обеспечения согласованности все открытые типы и их члены должны быть задокументированы.
  • Закрытые члены можно также задокументировать с помощью XML-комментариев. Однако это приводит к раскрытию внутренних (возможно, конфиденциальных) процессов библиотеки.
  • Как минимум, типы и их члены должен иметь тег <summary>, так как его содержимое требуется для IntelliSense.
  • Текст документации должны быть написан с использованием законченных предложений, в конце которых ставится точка.
  • Разделяемые классы полностью поддерживаются, и данные о документации объединяются в одну запись для этого типа.

Документация XML начинается с ///. При создании проекта шаблоны добавляют несколько строк ///. Обработка этих комментариев имеет некоторые ограничения.

  • Документация должна представлять собой XML с правильным форматом. Если XML сформирован неправильно, компилятор выдает предупреждение. Файл документации будет содержать комментарий, в котором сообщается, что обнаружена ошибка.
  • Некоторые рекомендуемые теги имеют особые значения.
    • Тег <param> используется для описания параметров. При использовании этого тега компилятор проверяет, что параметр существует и все параметры описаны в документации. При сбое проверки компилятор выдает предупреждение.
    • Атрибут cref может быть присоединен к любому тегу для ссылки на элемент кода. Компилятор проверяет наличие этого элемента кода. При сбое проверки компилятор выдает предупреждение. Компилятор учитывает любые операторы using при поиске типа, описанного в атрибуте cref.
    • Тег <summary> используется технологией IntelliSense в Visual Studio для отображения дополнительных сведений о типе или элементе.

      Примечание

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

  • Разработчики могут создавать собственные наборы тегов. Компилятор скопирует их в выходной файл.

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

Компилятор проверяет синтаксис элементов, за которыми следует один * в следующем списке. Visual Studio предоставляет IntelliSense для тегов, проверенных компилятором, и всех тегов, за которыми следует ** в следующем списке. Помимо указанных здесь тегов, компилятор и Visual Studio проверяют теги <b>, <i>, <u>, <br/> и <a>. Компилятор также проверяет <tt>, который является устаревшим тегом HTML.

Примечание

Комментарии документации не применяются к пространству имен.

Чтобы ввести в текст комментария документации угловые скобки, используйте для символов < и > коды HTML &lt; и &gt; соответственно. Это показано в следующем примере.

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

Общие теги

<summary>

<summary>description</summary>

Тег <summary> следует использовать для описания типа или элемента типа. Чтобы добавить дополнительную информацию в описание типа, используйте <remarks>. Чтобы включить средства документации, такие как DocFX и Sandcastle, для создания внутренних гиперссылок на страницы документации для элементов кода, используйте атрибут cref. Текст в теге <summary> является единственным источником сведений о типе для технологии IntelliSense и также отображается в окне обозревателя объектов.

<remarks>

<remarks>
description
</remarks>

Тег <remarks> позволяет добавить сведения о типе или члене типа, дополняющие информацию, указанную с помощью тега <summary>. Эти сведения отображаются в окне "Обозреватель объектов". Этот тег может содержать более длинные объяснения. Возможно, вы обнаружите, что использование разделов CDATA для разметки упрощает написание. Такие средства, как docfx, обрабатывают текст разметки в разделах CDATA.

Члены документа

<returns>

<returns>description</returns>

Тег <returns> следует использовать в комментариях к объявлению метода для описания возвращаемого значения.

<param>

<param name="name">description</param>
  • name: имя параметра метода. Имя заключается в двойные кавычки (" "). Имена параметров должны соответствовать сигнатуре API. Если один или несколько параметров не охвачены, компилятор выдает предупреждение. Компилятор также выдает предупреждение, если значение name не соответствует формальному параметру в объявлении метода.

Тег <param> следует использовать в комментариях к объявлению метода для описания одного из параметров такого метода. Чтобы задокументировать несколько параметров, используйте несколько тегов <param>. Текст тега <param> отображается в IntelliSense, обозревателе объектов и веб-отчете по комментариям к коду.

<paramref>

<paramref name="name"/>
  • name: имя параметра, на который указывается ссылка. Имя заключается в двойные кавычки (" ").

Тег <paramref> позволяет указать, что слово в комментариях к коду, например в блоке <summary> или <remarks>, ссылается на параметр. В XML-файл такое слово может выделяться особым образом, например курсивом или полужирным шрифтом.

<exception>

<exception cref="member">description</exception>
  • cref = "member": ссылка на исключение, которое доступно из текущей среды компиляции. Компилятор проверяет, существует ли исключение, и приводит member к каноническому имени элемента в выходных XML-данных. member необходимо заключать в двойные кавычки (" ").

Тег <exception> служит для указания возможных исключений. Этот тег может применяться к определениям методов, свойств, событий и индексаторов.

<value>

<value>property-description</value>

Тег <value> позволяет описывать значение, которое представляется свойством. При добавлении свойства с помощью мастера создания кода из среды разработки Visual Studio .NET для нового свойства будет добавлен тег <summary>. Следует вручную добавить тег <value> для описания значения, которое представляется свойством.

Форматирование выходных данных документации

<para>

<remarks>
    <para>
        This is an introductory paragraph.
    </para>
    <para>
        This paragraph contains more details.
    </para>
</remarks>

Тег <para> используется внутри другого тега, например <summary>, <remarks> или <returns>, и позволяет добавить к тексту структуру. Тег <para> создает абзац с двойным отступом. Используйте тег <br/>, если хотите добавить в него один абзац.

<list>

<list type="bullet|number|table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>Assembly</term>
        <description>The library or executable built from a compilation.</description>
    </item>
</list>

Блок <listheader> используется для определения строки заголовка в таблице или списке определений. При определении таблицы необходимо ввести данные для term в заголовке. Каждый элемент в списке указывается в блоке <item>. При создании списка определений необходимо указать одновременно term и description. Тем не менее для таблицы, маркированного или нумерованного списка достаточно ввести только description. Число блоков <item> в списке или таблице не ограничено.

<c>

<c>text</c>

С помощью тега <c> можно указать, что текст в описании необходимо пометить как код. Чтобы определить несколько строк в качестве кода, используйте тег <code>.

<code>

<code>
    var index = 5;
    index++;
</code>

Тег <code> используется для указания нескольких строк кода. С помощью тега <c> можно указать, что однострочный текст в описании необходимо пометить как код.

<example>

<example>
This shows how to increment an integer.
<code>
    var index = 5;
    index++;
</code>
</example>

Тег <example> позволяет указать пример использования метода или другого элемента библиотеки. Пример обычно включает использование тега <code>.

Повторное использование текста документации

<inheritdoc>

<inheritdoc [cref=""] [path=""]/>

Наследование XML-комментариев от базовых классов, интерфейсов и аналогичных методов. Использование inheritdoc позволяет обойтись без копирования и вставки одинаковых XML-комментариев и автоматически поддерживать их синхронизацию. Обратите внимание, что при добавлении тега <inheritdoc> к типу все члены также будут наследовать эти комментарии.

  • cref: указывает элемент, из которого следует наследовать документацию. Унаследованные теги не переопределяют уже определенные теги для текущего элемента.
  • path: запрос с выражением XPath, в результате которого выводится набор узлов. С помощью этого атрибута можно отфильтровать теги, которые следует включить в наследуемую документацию или исключить из нее.

Добавьте XML-комментарии в базовые классы или интерфейсы, и InheritDoc скопирует их во все реализации классов. Добавьте XML-комментарии в синхронные методы, и InheritDoc скопирует их в асинхронные версии аналогичных методов. Если нужно скопировать комментарии из определенного элемента, укажите нужный элемент в атрибуте cref.

<include>

<include file='filename' path='tagpath[@name="id"]' />
  • filename: имя XML-файла, содержащего документацию. Имя файла может быть квалифицировано с помощью относительного пути к файлу исходного кода. filename необходимо заключать в одинарные кавычки (' ').
  • tagpath: путь тегов в filename, который ведет к тегу name. Путь необходимо заключать в одинарные кавычки (' ').
  • name: спецификатор имени в теге, предшествующий комментариям. name будет иметь идентификатор id.
  • id: идентификатор тега, который предшествует комментариям. Идентификатор заключается в двойные кавычки (" ").

Тег <include> позволяет задать ссылку на комментарии в другом файле, которые описывают типы и элементы вашего исходного кода. Включение внешнего файла является альтернативой размещению комментариев документации непосредственно в файле исходного кода. Помещая комментарии документации в отдельный файл, вы можете реализовать управление их версиями отдельно от версий исходного кода. В этом случае файл исходного кода может быть извлечен для изменения одним пользователем, а файл документации — другим. Тег <include> использует XML-синтаксис XPath. Сведения об использовании тега <include> см. в документации по XPath.

<see>

/// <see cref="member"/>
// or
/// <see cref="member">Link text</see>
// or
/// <see href="link">Link Text</see>
// or
/// <see langword="keyword"/>
  • cref="member": ссылка на член или поле, которые доступны для вызова из текущей среды компиляции. Компилятор проверяет, существует ли элемент кода, и передает member в имя элемента в выходных XML-данных. member необходимо заключать в двойные кавычки (" "). Можно указать другой текст ссылки для "cref", используя отдельный закрывающий тег.
  • href="link": гиперссылка на заданный URL-адрес. Например, <see href="https://github.com">GitHub</see> формирует гиперссылку с текстом GitHub, которая ведет на сайт https://github.com.
  • langword="keyword": ключевое слово языка, например true.

Тег <see> позволяет задать ссылку из текста. С помощью тега <seealso> можно указать, что текст должен быть размещен в разделе "См. также". Используйте атрибут cref для создания внутренних гиперссылок на страницы документации для элементов кода. Вы включаете параметры типа, чтобы указать ссылку на универсальный тип или метод, например cref="IDictionary{T, U}". Кроме того, href является допустимым атрибутом, который будет функционировать как гиперссылка.

<seealso>

/// <seealso cref="member"/>
// or
/// <seealso href="link">Link Text</seealso>
  • cref="member": ссылка на член или поле, которые доступны для вызова из текущей среды компиляции. Компилятор проверяет, существует ли элемент кода, и передает member в имя элемента в выходных XML-данных. member необходимо заключать в двойные кавычки (" ").
  • href="link": гиперссылка на заданный URL-адрес. Например, <seealso href="https://github.com">GitHub</seealso> формирует гиперссылку с текстом GitHub, которая ведет на сайт https://github.com.

С помощью тега <seealso> можно указать текст, который должен отображаться в разделе См. также. Тег <see> позволяет задать ссылку из текста. Тег seealso нельзя вложить в тег summary.

Атрибут cref

Атрибут cref в теге XML-документации означает "кодовая ссылка". Он указывает, что текст внутри тега представляет собой элемент кода, например тип, метод или свойство. Средства создания документации, такие как DocFX и Sandcastle, используют атрибуты cref для автоматического создания гиперссылок на страницу, где документирован тип или член.

Атрибут href

Атрибут href означает ссылку на веб-страницу. Его можно использовать для прямой ссылки на интерактивную документацию по API или библиотеке.

Универсальные типы и методы

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>
  • TResult: имя параметра типа. Имя заключается в двойные кавычки (" ").

Тег <typeparam> следует использовать в комментариях к объявлению универсального типа или метода для описания параметра типа. Добавьте такой тег для каждого параметра типа универсального типа или метода. Текст для тега <typeparam> будет отображаться в IntelliSense.

<typeparamref>

<typeparamref name="TKey"/>
  • TKey: имя параметра типа. Имя заключается в двойные кавычки (" ").

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

Пользовательские теги

Все описанные выше теги распознаются компилятором C#. Тем не менее пользователь может определять собственные теги. Инструменты, такие как Sandcastle, обеспечивают поддержку дополнительных тегов (например, <event> и <note>) и даже поддержку пространств имен документирования. Средства создания пользовательской или внутренней документации также можно использовать со стандартными тегами. Кроме того, поддерживается несколько выходных форматов — от HTML до PDF.