csharp-docstrings

C# Docstrings

Use this skill to add or normalize XML documentation comments in C# code so external tools can discover API intent without reverse-engineering the implementation.

Intent Router

Need	Load
preferred syntax, extraction path, and caveats	references/docstrings.md

Quick Start

1. Inspect the repository for an existing documentation convention.
2. Preserve an established machine-readable style when it already works with external tooling.
3. Otherwise standardize on XML documentation comments for the requested C# surface.
4. Document public and externally consumed symbols before private helpers.
5. Keep names, parameters, return semantics, and examples aligned with the real code.

Workflow

• identify the externally consumed surface before adding comments or rewriting existing documentation
• add documentation directly adjacent to the declaration or symbol that external tools inspect
• prefer concise summaries first, then parameters, returns, exceptions, examples, or side effects when the format supports them
• mention or preserve the extraction path used by the surrounding toolchain
• keep migrations incremental when mixed styles already exist in a large file or module

Output Pattern

• state the convention being applied and why it matches the surrounding toolchain
• show declaration-adjacent documentation blocks rather than detached prose
• mention extraction or verification commands when they help confirm the result
• call out any symbols intentionally left undocumented because they are private or out of scope

Canonical Pattern

/// <summary>Add two integers.</summary>
/// <param name="a">Left operand.</param>
/// <param name="b">Right operand.</param>
/// <returns>Sum of the operands.</returns>
int Add(int a, int b);

Extraction Path

dotnet build -p:GenerateDocumentationFile=true
docfx build