C# Documentation Best Practices

XML documentation standards and patterns for C# public APIs and members.

- Use <summary> for one-sentence descriptions starting with a present-tense verb, and <remarks> for implementation details, usage notes, or additional context

- Employ specific tags for different member types: <param> and <returns> for methods, <value> for properties, <typeparam> for generics, and <exception cref> for thrown exceptions

- Follow prescribed wording patterns for Boolean parameters and return values, enum parameters, and out parameters to ensure consistency across documentation

- Use <see cref>, <seealso>, <paramref>, and <inheritdoc/> to create cross-references and reduce duplication across the API surface

C# Documentation Best Practices

- Public members should be documented with XML comments.

- It is encouraged to document internal members as well, especially if they are complex or not self-explanatory.

Guidance for all APIs

- Use <summary> to provide a brief, one sentence, description of what the type or member does. Start the summary with a present-tense, third-person verb.

- Use <remarks> for additional information, which can include implementation details, usage notes, or any other relevant context.

- Use <see langword> for language-specific keywords like null, true, false, int, bool, etc.

- Use <c> for inline code snippets.

- Use <example> for usage examples on how to use the member.

- Use <code> for code blocks. <code> tags should be placed within an <example> tag. Add the language of the code example using the language attribute, for example, <code language="csharp">.

- Use <see cref> to reference other types or members inline (in a sentence).

- Use <seealso> for standalone (not in a sentence) references to other types or members in the "See also" section of the online docs.

- Use <inheritdoc/> to inherit documentation from base classes or interfaces.

- Unless there is major behavior change, in which case you should document the differences.

Methods