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

  • Статья

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

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

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

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

<remarks>

<remarks>
description
</remarks>

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

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

<возвращает>

<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>property-description</value>

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

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

<p>ara

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

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

<список>

<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>
    var index = 5;
    index++;
</code>

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

<Пример>

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

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

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

<наследуемая>

<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.

Например, следующий исходный <include> код использует тег для включения примечаний. Путь к файлу относительно источника.

namespace MyNamespace;

public class MyType
{
    /// <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    /// <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    /// <include file="MyAssembly.xml" path="doc/members/member[@name='M:MyNamespace.MyType.MyMethod']/*" />
    public int MyMethod(int p) => p;
}

Xml-источник для файла включения показан в следующем примере. Он структурирован так же, как XML-файл, созданный компилятором C#. XML-файл может содержать текст для нескольких методов или типов, если выражение XPath может их идентифицировать.

<?xml version="1.0"?>
<doc>
    <members>
        <member name="M:MyNamespace.MyType.MyMethod">
            <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
            <summary>This is the summary of MyMethod. It comes from the included file.</summary>
        </member>
    </members>
</doc>

Выходные данные XML для этого метода показаны в следующем примере:

<member name="M:MyNamespace.MyType.MyMethod(System.Int32)">
    <summary>This is the summary of MyMethod. It comes from the included file.</summary>
    <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
</member>

Совет

Команда среды выполнения .NET широко использует <include> тег в своей документации. Вы можете просмотреть множество примеров, выполнив поиск в репозиторииdotnet/runtime.

<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> можно указать текст, который должен отображаться в разделе См. также. Используйте <для> указания ссылки из текста. Тег 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, поддерживают дополнительные теги, такие как <события> и <заметки>, и даже поддерживают документирование пространств имен. Средства создания пользовательской или внутренней документации также можно использовать со стандартными тегами. Кроме того, поддерживается несколько выходных форматов — от HTML до PDF.