Edit

Share via

How to write good /// docs for .NET API reference

The ultimate goal for .NET API docs is to have the /// XML comments in the .NET source code be the "source of truth". For MSBuild, ASP.NET Core, and EF Core, this goal has been met. However, currently the dotnet-api-docs repo remains the source of truth for some namespaces in the .NET API reference. This dotnet/runtime issue tracks the effort to backport .NET docs and make the dotnet/runtime repo the source of truth. The presence or absence of the "edit" button on a page often indicates that the dotnet-api-docs repository is the source of truth. If it's missing, the source of truth is likely the /// comments in the source repo.

This article provides tips about writing good doc comments within the source code itself.

Good comments make for good documents

.NET API triple-slash comments are transformed into public documentation on learn.microsoft.com and also appear in IntelliSense in the IDE. The comments should be:

  • Complete—empty doc entries for methods, parameters, exceptions, and so on, make the APIs feel under-supported, temporary, or trivial.
  • Correct—readers scan for critical details and become frustrated when key information is missing or incorrect.
  • Contextual—readers land on this page from search and need to know how and when to use the API, and what the code implications are.
  • Polished—poor or hasty grammar and spelling can confuse the reader and make even simple calls ambiguous; also, poor presentation communicates low investment.

Best practices

  1. Use cref instead of href to link to another type or method.

    Correct: <param name="configFile">An <see cref="XmlConfigResource" /> object.</param>

    Incorrect: <param name="configFile">An <a href="https://learn.Microsoft.com/{path}/XmlConfigResource"></a> object.</param>

  2. When referencing parameters, wrap the parameter name in a <paramref> tag, for example, The offset in <paramref name="source" /> where the range begins..

  3. If you have more than one paragraph in the doc comment, separate the paragraphs with <para> tags.

  4. Wrap code examples in <code> tags within <example> tags.

  5. Use <seealso> to add links to other APIs in the autogenerated "See Also" section.

XML doc tags

Tag Purpose Example
<altmember> Adds a "See also" link to the specified API. <altmember cref="System.Console.Out" />
<c> Formats the specified text as code within a description. Gets the current version of the language compiler, in the form <c>Major.Minor.Revision.Build</c>.
<code> Formats multiple lines as code. <code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code>
<example> Adds a code example under the "Example" H2 heading. <example><code language="csharp">using(logger.BeginScope("Processing request from {Address}", address)) { }</code></example>
<exception> Describes an exception the API can throw. <exception cref="T:System.ArgumentException">No application identity is specified in <paramref name="identity" />.</exception>
<include> Refer to comments in another file that describe the APIs in your source code. <include file="../docs/AbsoluteLayout.xml" path="Type[@FullName='Microsoft.Maui.Controls.AbsoluteLayout']/Docs/*" />

.NET MAUI example
<inheritdoc> Inherit XML comments from base classes, interfaces, and similar methods. <inheritdoc />
<list> Creates a bulleted or numbered list. <list type="bullet"><item><description>Set the root path to the result.</description></item><item><description>Load host configuration.</description></item></list>
<para> Separates paragraphs.
<paramref> Refers to a method parameter. Returns the activity with the specified <paramref name="id" />.
<related> Adds a "See also" link to the specified article. <related type="Article" href="/dotnet/framework/ado-net-overview">ADO.NET overview</related>
<see cref> Links to another API. Describes the behavior that caused a <see cref="Scroll" /> event.
<see langword> Formats the specified text as code. Gets the value of the <see langword="Accept-Ranges" /> header for an HTTP response.
<seealso> Adds a "See also" link to the specified API. <seealso cref="T:System.Single" />
<typeparamref> Refers to a type parameter. The <typeparamref name="THandler" /> is resolved from a scoped service provider.

For more information, see Recommended XML tags for C# and the C# specification. The ECMAXML spec also has good information, although be aware that there are some differences between ECMAXML and /// documentation comments (for example, cref targets are fully expanded and have prefixes in ECMAXML).

Cross references

When you use a <see cref> tag to link to another API, there's no need to add a prefix to the type name, such as T: for type or M: for method. In fact, code analysis rule CA1200 flags code comments that add a prefix to the type name in a cref tag. However, there are a couple exceptions to this rule:

  • When you want to link to the general form of a method that has more than one overload, the C# compiler doesn't currently support that. The workaround for docs is to prefix the method name with O: in source code (or Overload: in ECMAXML) and suppress