writing-xml-doc-comments
Write or review C# XML documentation comments on public API surface. USE FOR: adding or reviewing XML documentation on public types, members, parameters, type parameters, and return values. DO NOT USE FOR: ordinary code comments (use csharp-style), or prose, markdown, README, and wiki text; those follow the writing standard.
Nice3point · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Nice3point/revit-skills --skill writing-xml-doc-commentsAbout this skill
name: writing-xml-doc-comments description: > Write or review C# XML documentation comments on public API surface. USE FOR: adding or reviewing XML documentation on public types, members, parameters, type parameters, and return values. DO NOT USE FOR: ordinary code comments (use csharp-style), or prose, markdown, README, and wiki text; those follow the writing standard. license: MIT
Writing XML Doc Comments
Write reference documentation to an enterprise production standard, not tutorial or learning material. Document the contract a caller depends on, not the mechanics a reader can see in the signature. The conventions match Microsoft's own guidance for writing .NET API reference comments: complete, correct, contextual, and polished. Every tag opens with a third-person singular verb, has no personal pronoun, and states a contract instead of a mechanism.
When to use
- Adding a public or protected type, member, or contract to a library or a shared assembly.
- Reviewing XML documentation for coverage, tag order, opening phrasing, and contract accuracy.
- Closing documentation gaps reported by CS1591 or CS1573.
Rules
- Give every public and protected type, member, parameter, type parameter, and return value its tag.
- Put the text on its own line between the opening and closing tag, indented four spaces past the
///marker; use the one-line form for a single short clause. - Indent a nested tag one level further, and indent a
<code>block to the level its rendered output needs. - Write one sentence per tag and end it with a period; move a second sentence to
<remarks>. - Ignore the line length; the text of a tag occupies one line however long it runs, and no line is wrapped by hand.
- State the contract; never restate the name or the parameter list in words.
- Describe observable behavior, not the current implementation.
- Describe the member as it stands, not the change that produced it. The caller reading the documentation has no previous version to compare against.
- State facts in the present indicative; never argue why.
- Never use a personal pronoun (
you,we,I); state the fact about the member instead. - Cut every purpose, result, cause, or comparison clause (
so,that makes,which makes,because,rather than); if the clause states a fact the reader needs, make it its own sentence.
Tag order
Write the tags in this order.
<summary><value>— a property whose default or unit the caller needs<typeparam>— one per type parameter, in declaration order<param>— one per parameter, in declaration order<returns><exception>— one per contract throw<remarks><example>
Summary opening by member kind
The skeleton is identical for every declaration; the opening phrase is what changes.
| Declaration | Summary opens with | Example |
|---|---|---|
| Class, struct, record | Represents …, Provides …, Defines … | Represents the host portion of a URI. |
| Static class with extensions | Extension methods for …, Provides extension methods for … | Provides extension methods for <see cref="IEndpointRouteBuilder" /> to add endpoints. |
| Interface | Defines a contract that …, Provides an interface for … | Defines a contract that represents the result of an HTTP endpoint. |
| Attribute | Specifies … | Specifies a collection of tags in <see cref="Endpoint.Metadata" />. |
| Exception type | Represents … error | Represents an HTTP request error. |
| Delegate | A function that …, A delegate that … | A function that can process an HTTP request. |
| Enum | Determines …, Indicates whether … | Determines how cookie security properties are set. |
| Enum member | the effect of selecting the value | Opts out of compression over HTTPS. |
| Constant, static readonly field | the meaning of the value | HTTP status code 201. |
| Constructor | Initializes a new instance of the <see cref="T" /> class. | — |
| Read-only property | Gets … | Gets the HTTP status code for this exception. |
| Read-write property | Gets or sets … | Gets or sets the prefix used to identify the current object. |
| Boolean property | Gets a value indicating whether … | — |
| Event | An event that fires when …, An event that is raised when … | An event that is raised when a field value changes. |
| Factory method | `Creates a <see cref="T |