XML tags and formatting

Required XML tags

Depending on the type of API you're documenting, the required XML tags might be different. For example, methods require <returns> and <param> but enums don't.

<summary>: A one-line description of the API. All APIs must have a summary. The summary shows up in intelligent code completion tools such as Intellisense.
<param name="thing1">: Each function parameter requires this tag.
<typeparam name="thing2">: Each generic type parameter requires this tag.
<returns>: Non-void functions require this tag.
<value>: Fields and properties require this tag.

For information on which XML tags your API requires, refer to Guidelines for C# API documentation.

If you're writing documentation for a supported package, you must include all required XML tags for all public APIs. Otherwise, the package will fail Documentation standard US-0041. If you're writing documentation for an experimental package, this standard is not mandatory. However, you should still add all required XML tags because:

If any are missing, there is blank space in the documentation where that text should be.
Adding them will be a requirement when your the package leaves experimental.

You can configure Rider or any other IDEs to add the required tags in a /// comment block for you.

Optional XML tags

Alongside the required XML tags, there are also optional XML tags that don't affect the output of the documentation if you choose to omit them. However, it's recommended that you use them where possible.

<remarks>: Any additional or in-depth information. All but the simplest APIs should have a remarks section.
<example>: For code examples. The code itself goes inside a nested <code> element.
<see>: Link to other API types in the same package. Use inline with other text.
<seealso>: Like <see>, but also makes a list of see also links. Can be inline or top-level.

For information on which option XML tags you can include for your API, as well as guidance on when to use them, refer to Guidelines for C# API documentation.

Things to watch out for

Because the documentation is in XML, you can't use angle braces < >. To write the name of a generic function such as Sum<T>, use < and > in text, e.g. Sum<T>. In cref links, replace the angle brace with curly braces e.g <see cref="Sum{T}"/>.
When you use PMDT to generate the documentation to test your changes, always clear your browser cache.
Most block-level elements don't get nested. For example, you can't put an <example> or <param> element inside a <remarks> element.

Simple class example

This example shows you how to use XML tags to create documentation for a simple class.

/// <summary>
/// The Calculator class provides basic math calculations.
/// </summary>
/// <remarks>The math functions implemented by Calculator favor speed 
/// over accuracy.
/// Use <see cref="SlowCalculator"/> when you need accurate results.</remarks>
/// <seealso cref="SlowCalculator"/>
public class Calculator
{
    /// <summary>
    /// The storage register of this calculator.
    /// </summary>
    /// <value>Stores the intermediate results of the current calculation.</value>
    public int Register;

    /// <summary>
    /// Adds the operand to the Register.
    /// </summary>
    /// <param name="operand">The number to add to the current sum.</param>
    /// <typeparam name="T">A numeric type.</typeparam>
    /// <returns>The result so far.</returns>
    public T Sum(T operand)
    {
        Register += (int)(object)operand;
        return (T)(object)Register;
    }

    /// <summary>
    /// Gets the result of the current operation.
    /// </summary>
    /// <returns>The current Register value.</returns>
    public int Result()
    {
        return Register;
    }

    /// <summary>
    /// Clears the current calculation, setting Register to zero.
    /// </summary>
    public void Clear()
    {
        Register = 0;
    }
}

Code examples

To include code examples, put them in an <example> element:

/// <example>
///     The following example shows how to sum:
///     <code>
///         var calc = new Calculator();
///         calc.Sum(73.23);
///         calc.Sum(21.3);
///         print(calc.Result());
///     </code>
/// </example>

To extract code examples from another file, wrap the example lines in a named region and include it in the XMLDoc comment with:

       /// <example>
       /// <code source="../Doc.CodeSamples.Tests/CodeExamples.cs" region="builderclassexample" title="ExampleTitle"/>
       /// </example>

In the Entities package, code examples for the docs are kept in Doc.CodeSamples.Tests. These classes get compiled, but not executed.

To APIs from XMLdoc

To link to other APIs in the same package, use <see cref="APIName">. The cref attribute is the scoped name. In other words, to link to a class in the same namespace, you can just use the class name; and to link to a method in the current class, you can just use the method name.

There are several ways to reference items with parameter types and numbers. These can be useful to specify particular overloads for the link, for example:

    public T Sum<T,R,S>(T t, R r, S s)

Could reference any of the following:

    <seealso cref="SlowCalculator.Sum"/>
    <seealso cref="SlowCalculator.Sum{T,R,S}(T,R,S)"/>
    <seealso cref="SlowCalculator.Sum``3(T,R,S)"/>
    <seealso cref="SlowCalculator.Sum``3(``1,``2,``3)"/>

To URLs

To link to URLs, use markdown links, such as [Unity](http://www.unity3d.com) in running text.

To manual articles from XMLdoc

To link to manual content in the same package, use an xref or a relative link: ../manual/topic_file.md. All the manual files are in the manual folder; all the API files are in the api folder with no subfolders in either case. Example: [Entities](../manual/ecs_entities.md) You can use .html in the link, but then the link checker doesn't validate it. Xrefs have the benefit that someone can move the files into subfolders or change their names and the links will still work. The UID used in the xref must be assigned at the top of the markdown page. (UIDs to APIs are based on the type name with parameters, where relevant.)

To link to the manual from an API comment, use the uid value assigned to the page, you can use the following xref-based syntaxes:

Markdown: [](xref:external-links) -- Links
html with xref URL scheme: <a href="xref:external-links"/> -- Links
DocFX syntax: <xref href="external-links"/> -- Links
DocFX shorthand: @external-links -- Links

The above forms use the page title as the link display text (To also set the displayed link text:

Markdown: [External links](xref:external-links) -- External links
html with xref URL scheme: <a href="xref:external-links">External links</a> -- External links
DocFX syntax: <xref href="external-links">External links</xref> -- External links
DocFX shorthand: @"external-links?text=External links" -- External links

DocFX guide for more specialized syntaxes for controlling what is displayed for xrefs to APIs.

To API from manual

The same thing works from manual content to API content e.g [EntityQuery](../api/Unity.Entities.EntityQuery.html) In this case, you must add .html to the end of the link.

You can also use DocFX's special xref link format: [EntityQuery.SetFilter()](xref:Unity.Entities.EntityQuery.SetFilter*)

The xref must be fully qualified and DocFX "mangles" the names, so it can be hard to manually guess links for generic methods and those with parameters. DocFX creates an xrefmap file that contains the uid that you can use to reference a function or other member.

The xrefmap file is in the root of the generated documentation. If the API exists in already published documentation, you can find it online. For example, the package name and version are https://docs.unity3d.com/Packages/com.unity.entities@0.17/xrefmap.yml. You can also generate the documentation locally and find the file on your hard drive.

For example, the entry for the link above is:

- uid: Unity.Entities.EntityQuery.SetFilter*
  name: SetFilter
  href: api/Unity.Entities.EntityQuery.html#Unity_Entities_EntityQuery_SetFilter_
  commentId: Overload:Unity.Entities.EntityQuery.SetFilter
  isSpec: "True"
  fullName: Unity.Entities.EntityQuery.SetFilter
  nameWithType: EntityQuery.SetFilter

This links to the first SetFilter function. You can also link to specific overrides, such as xref:Unity.Entities.EntityQuery.SetFilter``1(``0)

You can search within this file for an API to determine the correct uid to use in the link. For more information, refer to External linking

Formatting

Markdown is the preference over XML formatting, but both are supported.

`code`
**bold**
*italic*