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

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

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

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

Документация определяет любую функцию, впервые представленную в последних трех версиях языка или в текущих общедоступных предварительных версиях.

Совет

Чтобы узнать, когда функция впервые появилась в C#, ознакомьтесь со статьей по журналу версий языка C#.

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

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

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

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

      Примечание.

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

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

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

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

Примечание.

Такие теги <br/> HTML полезны для форматирования в комментариях документации. Тег <br/> создает разрывы строк, а другие html-теги предоставляют форматирование текста. Эти теги работают в подсказках IntelliSense и созданной документации.

Примечание.

Комментарии к пространству имен нельзя применить к пространству имен.

Чтобы ввести в текст комментария документации угловые скобки, используйте для символов < и > коды 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 разделов для markdown делает его более удобным. Такие средства, как 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/>, если хотите добавить в него один абзац.

Ниже приведен пример, показывающий разницу между <para> и <br/>:

/// <summary>
/// Example using para tags:
/// <para>This is the first paragraph.</para>
/// <para>This is the second paragraph with double spacing.</para>
/// 
/// Example using br tags:
/// First line of text<br/>
/// Second line of text with single spacing<br/>
/// Third line of text
/// </summary>
public void FormattingExample()
{
    // This method demonstrates paragraph and line break formatting
}

<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>
    <item>
        <term>Namespace</term>
        <description>A logical grouping of related types such as classes and interfaces.</description>
    </item>
    <item>
        <term>Class</term>
        <description>A blueprint used to create objects, containing properties and methods.</description>
    </item>
</list>

Используйте <listheader> блок для определения строки заголовка таблицы или списка определений.

При определении таблицы:

  • Укажите запись term в заголовке.
  • Укажите каждый элемент в списке с блоком <item> . Для каждого itemиз них укажите запись для description.

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

  • Укажите запись term в заголовке.
  • Укажите каждый элемент в списке с блоком <item> . Каждый item должен содержать как a, term так и 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> .

<b>

<b>text</b>

<b> Используйте тег, чтобы сделать текст полужирным в комментариях к документации. Компилятор и Visual Studio проверяют этот тег форматирования HTML. Форматированный текст отображается в IntelliSense и созданной документации.

<i>

<i>text</i>

<i> Используйте тег, чтобы сделать текст курсивом в комментариях к документации. Компилятор и Visual Studio проверяют этот тег форматирования HTML. Форматированный текст отображается в IntelliSense и созданной документации.

<u>

<u>text</u>

<u> Используйте тег для подчеркивания текста в комментариях к документации. Компилятор и Visual Studio проверяют этот тег форматирования HTML. Форматированный текст отображается в IntelliSense и созданной документации.

<br/>

Line one<br/>Line two

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

<a>

<a href="https://example.com">Link text</a>

<a> Используйте тег для создания гиперссылок в комментариях к документации. Атрибут href задает URL-адрес для ссылки. Компилятор и Visual Studio проверяют этот тег форматирования HTML.

Примечание.

Компилятор также проверяет тег <tt>, который является устаревшим в HTML. <c> Вместо этого используйте тег для форматирования встроенного кода.

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

<inheritdoc>

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

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

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

Примечание.

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

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

Добавьте 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-данных. Поместите член в кавычки ("). Вы можете указать другой текст ссылки для a cref, используя отдельный закрывающий тег.
  • href="link": гиперссылка на заданный URL-адрес. Например, <see href="https://github.com">GitHub</see> формирует гиперссылку с текстом GitHub, которая ведет на сайт https://github.com. Используйте href вместо cref ссылки на внешние веб-страницы, так как cref предназначено для ссылок на код и не создает ссылки для внешних URL-адресов.
  • langword="keyword": ключевое слово языка, например true одно из других допустимых ключевых слов.

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

Вот пример, показывающий разницу между cref и href при ссылке на внешние URL-адреса:

/// <summary>
/// This method demonstrates URL linking:
/// <see cref="https://learn.microsoft.com/dotnet/csharp"/> (won't create clickable link)
/// <see href="https://learn.microsoft.com/dotnet/csharp">C# documentation</see> (creates clickable link)
/// </summary>
public void UrlLinkingExample()
{
    // This method demonstrates the difference between cref and href for URLs
}

<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 или библиотеке. Если вам нужно ссылаться на внешние URL-адреса в комментариях к документации, используйте href вместо cref, чтобы обеспечить, что ссылки кликабельны в подсказках IntelliSense и созданной документации.

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

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

  • Last updated on