Editja

Ixxerja permezz ta’

Recommended XML tags for C# documentation comments

C# documentation comments use XML elements to define the structure of the output documentation. One consequence of this feature is that you can add any valid XML in your documentation comments. The C# compiler copies these elements into the output XML file. While you can use any valid XML in your comments (including any valid HTML element), documenting code is recommended for many reasons.

The C# language reference documents the most recently released version of the C# language. It also contains initial documentation for features in public previews for the upcoming language release.

The documentation identifies any feature first introduced in the last three versions of the language or in current public previews.

Tip

To find when a feature was first introduced in C#, consult the article on the C# language version history.

What follows are some recommendations, general use case scenarios, and things that you should know when using XML documentation tags in your C# code. While you can put any tags into your documentation comments, this article describes the recommended tags for the most common language constructs. Adhere to these recommendations:

  • For the sake of consistency, document all publicly visible types and their public members.
  • You can also document private members by using XML comments. However, this approach exposes the inner (potentially confidential) workings of your library.
  • At a bare minimum, types and their members should have a <summary> tag.
  • Write documentation text using complete sentences that end with full stops.
  • Partial classes are fully supported, and documentation information is concatenated into a single entry for each type. If both declarations of a partial member have documentation comments, the comments on the implementing declaration are written to the output XML.

XML documentation starts with ///. When you create a new project, the templates put some starter /// lines in for you. The processing of these comments has some restrictions:

  • The documentation must be well-formed XML. If the XML isn't well formed, the compiler generates a warning. The documentation file contains a comment that says that an error was encountered.
  • Some of the recommended tags have special meanings:
    • The <param> tag describes parameters. If you use this tag, the compiler verifies that the parameter exists and that all parameters are described in the documentation. If the verification fails, the compiler issues a warning.
    • Attach the cref attribute to any tag to reference a code element. The compiler verifies that this code element exists. If the verification fails, the compiler issues a warning. The compiler respects any using directives when it looks for a type described in the cref attribute.
    • IntelliSense inside Visual Studio uses the <summary> tag to display additional information about a type or member.

      Note

      The XML file doesn't provide full information about the type and members (for example, it doesn't contain any type information). To get full information about a type or member, use the documentation file together with reflection on the actual type or member.

  • Developers are free to create their own set of tags. The compiler copies these tags to the output file.

Some of the recommended tags can be used on any language element. Others have more specialized usage. Finally, some of the tags are used to format text in your documentation. This article describes the recommended tags organized by their use.

The compiler verifies the syntax of the elements followed by a single * in the following list. Visual Studio provides IntelliSense for the tags verified by the compiler and all tags followed by ** in the following list. In addition to the tags listed here, the compiler and Visual Studio validate the <b>, <i>, <u>, <br/>, and <a> tags. The compiler also validates <tt>, which is deprecated HTML.

Note

HTML tags like <br/> are useful for formatting within documentation comments. The <br/> tag creates line breaks, while other HTML tags provide text formatting. These tags work in IntelliSense tooltips and generated documentation.

Note

You can't apply documentation comments to a namespace.

If you want angle brackets to appear in the text of a documentation comment, use the HTML encoding of < and >, which is &lt; and &gt; respectively. The following example shows this encoding.

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

General tags

<summary>

<summary>description</summary>

Use the <summary> tag to describe a type or a type member. Use <remarks> to add supplemental information to a type description. Use the cref attribute to enable documentation tools such as DocFX and Sandcastle to create internal hyperlinks to documentation pages for code elements. The text for the <summary> tag appears in IntelliSense and in the Object Browser window.

<remarks>

<remarks>
description
</remarks>

Use the <remarks> tag to add information about a type or a type member, supplementing the information specified with <summary>. This information appears in the Object Browser window. This tag can include more lengthy explanations. You might find that using CDATA sections for markdown make writing it more convenient. Tools such as docfx process the markdown text in CDATA sections.

Document members

<returns>

<returns>description</returns>

Use the <returns> tag in the comment for a method declaration to describe the return value.

<param>

<param name="name">description</param>
  • name: The name of a method parameter. Enclose the name in quotation marks ("). The names for parameters must match the API signature. If one or more parameters aren't covered, the compiler issues a warning. The compiler also issues a warning if the value of name doesn't match a formal parameter in the method declaration.

Use the <param> tag in the comment for a method declaration to describe one of the parameters for the method. To document multiple parameters, use multiple <param> tags. The text for the <param> tag appears in IntelliSense, the Object Browser, and the Code Comment Web Report.

<paramref>

<paramref name="name"/>
  • name: The name of the parameter to refer to. Enclose the name in quotation marks (").

The <paramref> tag provides a way to indicate that a word in the code comments, such as in a <summary> or <remarks> block, refers to a parameter. You can process the XML file to format this word in a distinct way, such as by using a bold or italic font.

<exception>

<exception cref="member">description</exception>
  • cref = "member": A reference to an exception that's available from the current compilation environment. The compiler checks that the given exception exists and translates member to the canonical element name in the output XML. member must appear within quotation marks (").

The <exception> tag lets you specify which exceptions can be thrown. Apply this tag to definitions for methods, properties, events, and indexers.

<value>

<value>property-description</value>

The <value> tag lets you describe the value that a property represents. When you add a property by using the code wizard in the Visual Studio .NET development environment, it adds a <summary> tag for the new property. You manually add a <value> tag to describe the value that the property represents.

Format documentation output

<para>

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

Use the <para> tag inside a tag, such as <summary>, <remarks>, or <returns>, to add structure to the text. The <para> tag creates a double spaced paragraph. Use the <br/> tag if you want a single spaced paragraph.

Here's an example showing the difference between <para> and <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>

Use the <listheader> block to define the heading row of either a table or definition list.

When defining a table:

  • Supply an entry for term in the heading.
  • Specify each item in the list with an <item> block. For each item, supply an entry for description.

When creating a definition list:

  • Supply an entry for term in the heading.
  • Specify each item in the list with an <item> block. Each item must contain both a term and description.

A list or table can have as many <item> blocks as needed.

<c>

<c>text</c>

Use the <c> tag to mark text within a description as code. Use <code> to indicate multiple lines as code.

<code>

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

Use the <code> tag to indicate multiple lines of code. Use <c> to mark single-line text within a description as code.

<example>

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

Use the <example> tag to provide an example of how to use a method or other library member. An example commonly involves using the <code> tag.

<b>

<b>text</b>

Use the <b> tag to make text bold within documentation comments. The compiler and Visual Studio validate this HTML formatting tag. The formatted text appears in IntelliSense and generated documentation.

<i>

<i>text</i>

Use the <i> tag to make text italic within documentation comments. The compiler and Visual Studio validate this HTML formatting tag. The formatted text appears in IntelliSense and generated documentation.

<u>

<u>text</u>

Use the <u> tag to underline text within documentation comments. The compiler and Visual Studio validate this HTML formatting tag. The formatted text appears in IntelliSense and generated documentation.

<br/>

Line one<br/>Line two

Use the <br/> tag to insert a line break within documentation comments. Use this tag when you want a single spaced paragraph, as opposed to the <para> tag which creates double spaced paragraphs.

<a>

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

Use the <a> tag to create hyperlinks within documentation comments. The href attribute specifies the URL to link to. The compiler and Visual Studio validate this HTML formatting tag.

Note

The compiler also validates the <tt> tag, which is deprecated HTML. Use the <c> tag instead for inline code formatting.

Reuse documentation text

<inheritdoc>

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

Inherit XML comments from base classes, interfaces, and similar methods. By using inheritdoc, you eliminate unwanted copying and pasting of duplicate XML comments and automatically keep XML comments synchronized. When you add the <inheritdoc> tag to a type, all members inherit the comments as well.

  • cref: Specify the member to inherit documentation from. The inherited tags don't override already defined tags on the current member.
  • path: The XPath expression query that results in a node set to show. Use this attribute to filter the tags to include or exclude from the inherited documentation.

Note

Visual Studio automatically inherits XML documentation for undocumented members that override or implement documented members. This feature displays inherited documentation in IntelliSense and Quick Info without requiring the <inheritdoc> tag. However, this automatic inheritance only applies within the Visual Studio IDE and doesn't affect the XML documentation file generated by the compiler.

For public APIs in libraries that you distribute, explicitly use the <inheritdoc> tag or provide complete documentation to ensure the generated XML documentation file includes all necessary information for consumers of your library.

Add your XML comments in base classes or interfaces and let inheritdoc copy the comments to implementing classes. Add your XML comments to your synchronous methods and let inheritdoc copy the comments to your asynchronous versions of the same methods. To copy the comments from a specific member, use the cref attribute to specify the member.

<include>

<include file='filename' path='tagpath[@name="id"]' />
  • filename: The name of the XML file containing the documentation. You can qualify the file name with a path relative to the source code file. Enclose filename in single quotation marks (' ').
  • tagpath: The path of the tags in filename that leads to the tag name. Enclose the path in single quotation marks (' ').
  • name: The name specifier in the tag that precedes the comments. The name specifier has an id.
  • id: The ID for the tag that precedes the comments. Enclose the ID in quotation marks (").

By using the <include> tag, you can refer to comments in another file that describe the types and members in your source code. Including an external file is an alternative to placing documentation comments directly in your source code file. By putting the documentation in a separate file, you can apply source control to the documentation separately from the source code. One person can have the source code file checked out and someone else can have the documentation file checked out. The <include> tag uses the XML XPath syntax. Refer to XPath documentation for ways to customize your <include> use.

For example, the following source code uses the <include> tag to include remarks. The file path is relative to the source.

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;
}

The XML source for the include file is shown in the following sample. It's structured the same as the XML file generated by the C# compiler. The XML file can contain text for multiple methods or types, as long as an XPath expression can identify them.

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

The XML output for this method is shown in the following example:

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

Tip

The .NET Runtime team uses the <include> tag extensively in its documentation. You can see many examples by searching the dotnet/runtime repository.

<see>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>
  • cref="member": A reference to a member or field that you can call from the current compilation environment. The compiler checks that the given code element exists and passes member to the element name in the output XML. Place member within quotation marks ("). You can provide different link text for a cref, by using a separate closing tag.
  • href="link": A clickable link to a given URL. For example, <see href="https://github.com">GitHub</see> produces a clickable link with text GitHub that links to https://github.com. Use href instead of cref when linking to external web pages, as cref is designed for code references and doesn't create clickable links for external URLs.
  • langword="keyword": A language keyword, such as true or one of the other valid keywords.

The <see> tag lets you specify a link from within text. Use <seealso> to indicate that text should be placed in a See Also section. Use the cref attribute to create internal hyperlinks to documentation pages for code elements. Include the type parameters to specify a reference to a generic type or method, such as cref="IDictionary{T, U}". Also, href is a valid attribute that functions as a hyperlink.

Here's an example showing the difference between cref and href when referencing external URLs:

/// <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": A reference to a member or field that you can call from the current compilation environment. The compiler checks that the given code element exists and passes member to the element name in the output XML. member must appear within quotation marks (").
  • href="link": A clickable link to a given URL. For example, <seealso href="https://github.com">GitHub</seealso> produces a clickable link with text GitHub that links to https://github.com.

The <seealso> tag lets you specify the text that you might want to appear in a See Also section. Use <see> to specify a link from within text. You can't nest the seealso tag inside the summary tag.

cref attribute

The cref attribute in an XML documentation tag means "code reference." It specifies that the inner text of the tag is a code element, such as a type, method, or property. Documentation tools like DocFX and Sandcastle use the cref attributes to automatically generate hyperlinks to the page where the type or member is documented.

href attribute

The href attribute means a reference to a web page. You can use it to directly reference online documentation about your API or library. When you need to link to external URLs in your documentation comments, use href instead of cref to ensure the links are clickable in IntelliSense tooltips and generated documentation.

Generic types and methods

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>
  • TResult: The name of the type parameter. Enclose the name in quotation marks (").

The <typeparam> tag should be used in the comment for a generic type or method declaration to describe a type parameter. Add a tag for each type parameter of the generic type or method. The text for the <typeparam> tag is displayed in IntelliSense.

<typeparamref>

<typeparamref name="TKey"/>
  • TKey: The name of the type parameter. Enclose the name in quotation marks (").

Use this tag to enable consumers of the documentation file to format the word in some distinct way, for example in italics.

User-defined tags

All the tags outlined in this article represent those tags recognized by the C# compiler. However, a user is free to define their own tags. Tools like Sandcastle bring support for extra tags like <event> and <note>, and even support documenting namespaces. Custom or in-house documentation generation tools can also be used with the standard tags, and multiple output formats from HTML to PDF can be supported.

  • Last updated on