要点
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
SKILL.md
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 likenull,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 thelanguageattribute, for example,<code language="csharp">.
- Use
- 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.