Поделиться через

Рекомендуемые 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>. Для каждой itemиз них необходимо указать только запись description.

При создании списка определений:

  • Необходимо указать запись term в заголовке.
  • Каждый элемент в списке указывается в блоке <item>. Каждый item должен содержать как a, term так и 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-данных. Поместите член в кавычки ("). Можно указать другой текст ссылки для "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.