Table of Contents

XML documentation comments

Below, you can find a number of best practices for writing XML documentation comments.

XML documentation comments are structured comments used to provide API documentation. See the following example:

/// <summary>
/// Retrieves the value of the parameter with the specified ID.
/// </summary>
/// <param name="iID">The ID of the parameter.</param>
/// <returns>The value of the parameter. If no parameter with the specified ID exists in the protocol, <see langword="null"/> is returned.</returns>
/// <remarks>
///     <list type = "bullet" >
///         <item>
///             <description>This is a wrapper method for the Notify type 73 (NT_GET_PARAMETER) call.</description>
///         </item>
///         <item>
///             <description>When a GetParameter call is executed for a parameter that does not exist in the protocol, <see langword="null"/> is returned and the following message will be logged “NT_GET_PARAMETER for [parameterID] failed. 0x80040239”.</description>
///         </item>
///         <item>
///             <description>When calling this method on a numeric standalone parameter(i.e.a parameter having RawType set to either numeric text, signed number or unsigned number) that is not initialized, 0 will be returned.To determine whether a standalone parameter is uninitialized, the <see cref="IsEmpty"/> method should be used.</description>
///         </item>
///     </list>
/// </remarks>
/// <example>
///     <code>
///     string myValue = Convert.ToString(protocol.GetParameter(100));
///     </code>
/// </example>

Generating XML documentation

To generate an XML documentation file, you need to provide XML documentation comments for your source files. For more information, see:

In addition to providing the documentation comments, you also need to configure a setting to instruct the compiler to create an XML documentation file as output. This can be done in the Build tab of the Project Properties window. In the Output section, select the XML documentation file option:

Enabling this option will result in an XML file being generated in addition to the compiled assembly.

Using XML Documentation

If you reference a DLL file in your solution for which an XML documentation file exists, Visual Studio will provide additional IntelliSense information that is extracted from this documentation file:

Also, the Object Browser window provides information extracted from the XML documentation file:

XML documentation comments are not only useful for IDEs such as Visual Studio. Documentation tools such as docfx and Sandcastle Help File Builder also support processing XML documentation comments to automatically generate API documentation.

Best practices

Whereas the sections above provide more information on how to create and use XML documentation comments, this section provides some best practices related to the style that is typically used when writing XML documentation comments. Where applicable, examples will be provided from documented classes in Microsoft Learn.

General

  • All types and their members that are part of the public API should be properly documented.

  • Documentation text must start with an uppercase letter and end with a period.

  • Summaries for classes, methods, properties, events, etc. should start with a verb in third person singular form. For example: "Represents ...", "Initializes a new instance of ...", "Gets or sets ...", "Retrieves ...", etc.

  • Summaries should be kept small. Additional information can be provided in the <remarks> tag.

  • XML documentation comments must be valid XML. For example, use XML entities to avoid XML parsing issues when providing code examples:

Constructors

The summary of a constructor of a class should always start with the following, where className is the name of the class:

Initializes a new instance of the <see cref="className"/> class ...

For example, the String(Char[]) constructor of the System.String class is documented as follows:

Initializes a new instance of the String class to the Unicode characters indicated in the specified character array.

For structures, the following should be used:

Initializes a new instance of the <see cref="structName"/> structure ...

Properties

The summary of a property should always start with:

  • Gets for read-only properties
  • Sets for write-only properties (note: use of write-only properties is not recommended)
  • Gets or sets for read-write properties

For example, the Length property of the System.String class is documented as follows:

Gets the number of characters in the current String object.

For boolean properties, the summary should start with:

Gets a value indicating whether

For example, the IsFixedSize property of the Array class:

Gets a value indicating whether the Array has a fixed size.

In addition to the <summary> tag, for properties the <value> tag should be used. Here, a description can be provided for the property. For boolean properties, the documentation should have the following format:

<c>true</c> if …; otherwise, <c>false</c>

For example, the HasShutdownStarted property of the Environment class:

true if the current application domain is being unloaded or the CLR is shutting down; otherwise, false.

Methods

For methods, in addition to the <summary> tag, a <param> tag should be provided for each parameter. The return value must be documented with a <returns> tag (a void method should not have a <returns> tag).

For example, the EndsWith(Char) method of the String class:

/// <summary>
/// Determines whether the end of this string instance matches the specified character.
/// </summary>
/// <param name="value">The character to compare to the character at the end of this instance.</param>
/// <returns><c>true</c> if value matches the end of this instance; otherwise, <c>false</c>.</returns>
/// <remarks>This method performs an ordinal (case-sensitive and culture-insensitive) comparison.</remarks>

Exceptions

Members such as a constructor, method, properties, etc. that throw an exception should be documented with an <exception> tag for each type of exception that can be thrown. The cref attribute must be provided, specifying the exception class, and the documentation text must specify the reason for the exception:

<exception cref="ArgumentNullException"><paramref name="destination"/> is <see langword="null"/>.</exception>

For example, the CopyTo(Int32, Char[], Int32, Int32) method of the String class:

ArgumentNullException destination is null.

Note the use of the <paramref> tag to refer to a parameter. The <see> tag with the langword attribute can be used to denote a language keyword such as "null".

Tip
  • StyleCop.Analyzers (an implementation of the StyleCop rules using the .NET Compiler Platform API) can be of great help when creating XML documentation comments. See the documentation rules for an overview of all the rules related to XML documentation that are implemented.
  • The following Visual Studio extension can be used to easily detect spelling mistakes: Visual Studio Spell Checker
Propose changes