t1k:unity:base:docs
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | low |
| Tools | — |
How to invoke
Section titled “How to invoke”/t1k:unity:base:docs<file-or-directory> [--public-only] [--fill-missing-only]C# XML Documentation Generator
Section titled “C# XML Documentation Generator”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:
publictypes (class, interface, struct, record, delegate, enum)publicmembers (method, property, field, event, indexer)protectedmembers ofpublictypes- 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:
*.metanot relevant; skipAssets/Plugins/third-party DLLs
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “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 |
Workflow
Section titled “Workflow”- Locate target — single file or directory passed via
argument-hint. - Parse public surface — for each
.csfile, identifypublic/protecteddeclarations by reading the file. Skip if header matches generated pattern. - For each declaration, choose tags — see Tag Selection matrix below or tag-selection-matrix (
references/xmldoc-tag-reference.md#tag-selection-matrix). - Generate
///block — minimum<summary>; add<param>,<returns>,<exception>,<typeparam>per matrix. - 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. - Apply via Edit — insert directly above the declaration; preserve existing comments and indentation.
- Verify — re-read affected lines; confirm XML well-formedness (paired tags, escaped angle brackets via
<c>/<code>).
Tag Selection Matrix
Section titled “Tag Selection Matrix”| Member type | Required | Common | Optional |
|---|---|---|---|
| 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.
Writing Style (Quick Rules)
Section titled “Writing Style (Quick Rules)”- 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
Nameis 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 aDesigned for: …lede. Mechanical behavior alone leaves consumers guessing which API to pick.
Full style guide: writing-style.md (references/writing-style.md)
Hard rules
Section titled “Hard rules”- Generic
crefsyntax — 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)"vscref="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.csreadable 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". Onlytableuses<term>+<description>; bullet/number use<description>only.
References
Section titled “References”references/xmldoc-tag-reference.md— every supported tag with usage examplereferences/generation-rules.md— what to document, what to skip, inheritance rules, generic + record + extension patternsreferences/writing-style.md— sentence patterns, voice, common pitfallsreferences/examples.md— before/after for ExampleClass, Math library, generic class, positional record, extension methodsreferences/open-questions-register.md— project decision register format (numbered rows, provenance tags, DECIDED closing line) and mutation-survivor disposition
Source
Section titled “Source”Patterns from: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/examples