Skip to content

t1k:unity:base:docs

FieldValue
Modulebase
Version5.116.6
Effortlow
Tools—
/t1k:unity:base:docs
<file-or-directory> [--public-only] [--fill-missing-only]

Generate Microsoft-style XML doc comments for C# public APIs. Patterns sourced from learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/examples.

Scope boundary: this skill is the tag-syntax + writing-style mechanics reference for a single file, class, or method — no audit gate. Documenting a whole package/asmdef/submodule and proving completeness against audit-strict.py + doc-quality.py? Use t1k:unity:base:documents (../t1k-unity-base-documents/SKILL.md) instead — it owns that scope and links back here for per-tag syntax.

Documents:

  • public types (class, interface, struct, record, delegate, enum)
  • public members (method, property, field, event, indexer)
  • protected members of public types
  • Partially documented members (fill gaps only)

Skips:

  • private, internal, file-scoped declarations
  • Files with // <auto-generated> header
  • Generated files: *.Designer.cs, *.g.cs, *.generated.cs
  • Unity-generated: *.meta not relevant; skip Assets/Plugins/ third-party DLLs
IntentPath
“Document a single .cs file”Read file → identify public surface → generate per-member XML → Edit in-place
“Document a folder/project”Glob **/*.cs → loop per file; aggregate report
“Fill missing tags only”Detect /// blocks lacking required tags → add only what’s missing; never rewrite existing summaries
“Document a generic / record / extension”Apply <typeparam>, positional <param>, extension-receiver rules → generation-rules.md (references/generation-rules.md)
“Override / interface implementation”Write no doc block — the base/interface declaration is the SSOT. See “Inherited members” below
  1. Locate target — single file or directory passed via argument-hint.
  2. Parse public surface — for each .cs file, identify public/protected declarations by reading the file. Skip if header matches generated pattern.
  3. For each declaration, choose tags — see Tag Selection matrix below or tag-selection-matrix (references/xmldoc-tag-reference.md#tag-selection-matrix).
  4. Generate /// block — minimum <summary>; add <param>, <returns>, <exception>, <typeparam> per matrix.
  5. Leave inherited members undocumented — an override, an explicit interface impl (void IFoo.Bar()), and an implicit one (public void Bar() on a type declaring : IFoo) all inherit from the origin declaration. Document the origin instead.
  6. Apply via Edit — insert directly above the declaration; preserve existing comments and indentation.
  7. Verify — re-read affected lines; confirm XML well-formedness (paired tags, escaped angle brackets via <c>/<code>).
Member typeRequiredCommonOptional
Class / interface / struct / record<summary><remarks>, <typeparam> (if generic)<example>, <seealso>
Method<summary><param>, <returns>, <exception><example>, <typeparam>, <remarks>
Property<summary> (or <value>)<remarks><exception> (if accessor throws)
Field / event<summary>—<remarks>
Override / interface impl(none — document the origin)—<remarks> only when behavior genuinely differs
Positional record<summary> + <param> per positional<remarks>—
Extension member (C# 14)<summary> on extension<T>(...) block + <param> for receiver<typeparam>—
Generic type parameter<typeparam name="T"> on declaring type/method——

Full tag reference: xmldoc-tag-reference.md (references/xmldoc-tag-reference.md)

Inherited members — document the origin, not the implementation

Section titled “Inherited members — document the origin, not the implementation”

An override, an explicit interface implementation (void IFoo.Bar()), and an implicit one (public void Bar() on a type declaring : IFoo) all inherit their documentation from the declaration they implement. Put the doc on that origin — the abstract/virtual member or the interface — and leave the implementation bare. A block on the implementation is a duplicate that drifts out of sync with the origin; t1k:unity:base:documents’ audit-strict.py reports it as unrequired-override / unrequired-explicit-iface / unrequired-implicit-iface.

<inheritdoc/> is not a substitute for omission here: it restates the same inheritance the compiler and IDE already apply. Reach for it only in the narrow cases where the default inheritance is wrong or absent — pulling from a specific cref, or selecting part of a block with path (see Gotchas). One member can legitimately implement an interface member and carry its own <remarks> when the implementation’s behavior genuinely differs (a throwing Reset(), a degraded no-op provider); document only the difference.

  • Summary — one sentence, present tense, third person, terminating period. “Returns the sum of two integers.”
  • Param — noun phrase. “A double precision number.” NOT “The number to add.”
  • Returns — noun phrase, no leading “Returns ”. “The sum of two integers.”
  • Exception — “Thrown when <condition>.”
  • Wrap inline identifiers in <c>x</c>; multi-line code in <example><code>...</code></example>.
  • Cross-reference with <see cref="..."/>; parameter references with <paramref name="..."/>; type parameter refs with <typeparamref name="T"/>.
  • Do NOT restate what the name says (“Gets the name” on Name is noise — leave un-documented or describe semantics).
  • Domain intent — when the typical use case isn’t obvious from the signature (e.g., Pick(items, weights) is meant for gacha / loot tables / weighted A-B bucketing, not a generic uniform RNG), capture it in <remarks> with a Designed for: … lede. Mechanical behavior alone leaves consumers guessing which API to pick.

Full style guide: writing-style.md (references/writing-style.md)

  • Generic cref syntax — use curly braces inside cref: cref="GenericClass{T}". Angle brackets break XML parsing inside attributes.
  • Method-overload disambiguation — full signature required: cref="Math.Add(int, int)" vs cref="Math.Add(double, double)".
  • Positional records — primary-constructor parameters get <param> tags at TYPE level, not on auto-generated properties. The compiler hasn’t finalized property-level tags for positional records yet (per MS docs Jan 2026).
  • <inheritdoc> xpath — path="/returns" inherits only <returns>; path="//*[not(self::remarks)]" inherits everything except <remarks>.
  • C# 14 extension<T>(...) blocks — XML comments on the extension block PROPAGATE to all members declared in the block. Document the receiver once on the block; don’t repeat per member.
  • <include> external XML — for large APIs, move docs to a separate XML file and reference via <include file='...' path='XPath'/>. Keeps .cs readable but XPath errors are silent at compile time.
  • Auto-generated files — skip any file with // <auto-generated> first-line header OR matching *.Designer.cs, *.g.cs, *.generated.cs. Re-generated by tooling; doc edits are lost.
  • Unity-generated *.meta / Library/ — never edit; not C# source.
  • Existing partial docs — when filling gaps, preserve existing <summary> verbatim. Add only missing tags (typically <param>, <returns>, <exception>). Never silently rewrite.
  • StyleCop SA1600 compatibility — public-API-only configurations FAIL on missing docs but ALSO fail on docs for private members. Respect the analyzer scope; don’t over-document.
  • Paragraph spacing — <para> produces a double-spaced break; <br/> produces single-spaced. Use <para> between blocks of remarks, <br/> for line breaks within a paragraph.
  • <list> types — type="bullet", type="number", type="table". Only table uses <term> + <description>; bullet/number use <description> only.
  • references/xmldoc-tag-reference.md — every supported tag with usage example
  • references/generation-rules.md — what to document, what to skip, inheritance rules, generic + record + extension patterns
  • references/writing-style.md — sentence patterns, voice, common pitfalls
  • references/examples.md — before/after for ExampleClass, Math library, generic class, positional record, extension methods
  • references/open-questions-register.md — project decision register format (numbered rows, provenance tags, DECIDED closing line) and mutation-survivor disposition

Patterns from: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/examples