Skip to content

t1k:unity:base:documents

FieldValue
Modulebase
Version5.116.6
Effortmedium
Tools—

Keywords: audit-strict, doc comment, doc_search, doc-quality, documentation, intellisense, knowledge rag, knowledge-retrieval, param, public api, search surface, summary, typeparam, xml doc

/t1k:unity:base:documents

Unity XML Doc Comments — Public API Surface

Section titled “Unity XML Doc Comments — Public API Surface”

Add /// doc blocks to the externally-visible API surface, then prove it with the validators. Self-report is not evidence; the two bundled scripts are the gate.

Scope boundary: this skill owns whole-package/asmdef/submodule/repo documentation passes driven to both-validators-green. For per-tag XML syntax, writing-style rules, and a one-off doc comment on a single file with no gate, see t1k:unity:base:docs (../t1k-unity-base-docs/SKILL.md) — this skill defers to it for generation mechanics rather than re-deriving them.

Terminal window
S=.claude/skills/t1k-unity-base-documents/scripts
python3 $S/audit-strict.py <path> [<path> ...] # presence + placement, bidirectional
python3 $S/doc-quality.py <path> [<path> ...] # content quality + param/typeparam completeness

Done = both print summary: 0 … AND a non-zero scanned: count, and exit 0. Bidirectional: fill what is missing and delete what is unrequired. A doc block on an override is a failure just like a missing one.

What the summaries are FOR (beyond IntelliSense)

Section titled “What the summaries are FOR (beyond IntelliSense)”

These /// summaries are the search surface of the studio knowledge-RAG corpus: t1k:knowledge-retrieval’s doc_search indexes them (a vector embedding of the signature + summary, and a lexical arm that is Postgres FTS over the summary column only). Query technique and mechanics live in t1k:knowledge-retrieval’s query-technique.md — cite it, never restate it here. The consequence drives this skill’s quality rules: a public library type that ships with a missing, restated-name, or vague summary is not merely undocumented — it is unfindable by doc_search, because the lexical arm ANDs every lexeme over summary alone. That silently degrades studio-wide prior-art lookup (core search-before-you-build.md Pass 4, docs/library-feature-discovery-protocol.md corpus sweep) for every future project. The chain this skill owns: write the doc block → doc-quality.py gate → corpus summary column → doc_search finds it → the next project reuses instead of rebuilding.

Both are stdlib-only Python 3.10+ and skip generated trees — obj/, bin/, and Unity’s Library/, Temp/, PackageCache/. Each argument may be a directory (walked recursively for *.cs) or a single .cs file, and you may pass several at once — one process for a whole batch. --json on either for machine-readable output; doc-quality.py --threshold F tunes the name-restatement similarity cutoff (default 0.85).

scanned: <N> files accompanies every summary: line. Read it: summary: 0 with scanned: 0 means nothing was checked, not that everything passed.

Document (original declarations only):

  • public types and members — types, methods, properties, fields, events, delegates, indexers, operators, constructors, constants — at any nesting depth where the entire enclosing chain is also public (or protected inside a public type).
  • protected non-override members (part of the derived-class contract).
  • protected internal interface contract members (cross-assembly surface).
  • abstract / virtual declarations — these are the origin of the doc.

Skip — and delete the block if one exists (SSOT lives at the origin):

  • All override members, any visibility. The base abstract/virtual carries the doc; the override inherits it. Applies equally to Unity lifecycle hooks and business-logic overrides.
  • Interface implementations, explicit (void IFoo.Bar()) AND implicit (public void Bar() on a type declaring : IFoo) — IFoo.Bar carries the doc either way. The implicit form needs the interface body to be resolvable, so audit a whole package rather than a lone file.
  • Members of private/internal nested types — e.g. public sealed class Record inside private sealed class Blueprint. Requires the full enclosing-chain check, not just the member.
  • internal / private members, and private/internal type declarations.

<inheritdoc/> is exempt from the content check — it deliberately defers to the base.

audit-strict.py fails a correctly-worded doc that sits in the wrong place. The enforced layout:

// ← blank line (or a `{` / #region / outer scope)
/// <summary>Computes the reward multiplier for the current streak.</summary>
/// <param name="streak">Consecutive wins, clamped to the blueprint cap.</param>
/// <returns>Multiplier in [1, maxMultiplier].</returns>
#if UNITY_EDITOR // ← conditional preprocessor (optional)
[Conditional("DEBUG")] // ← attributes (optional)
#endif
// ReSharper disable once UnusedMember.Global
public float GetMultiplier(int streak) { … }

Rules the layout encodes:

  • The /// block sits at the top of the preamble. Attributes, #if, and // ReSharper disable once go below it, never above → otherwise misplaced-above-*.
  • One blank line above the block, separating it from the previous member’s } / ; → otherwise no-blank-above-*. Not required when the line above opens an outer scope ({, class Foo {), is a #region/#nullable/#pragma warning disable directive, a // ReSharper disable/restore region directive, or a plain // comment.
  • No blank line between the bottom of the /// block and the declaration → otherwise blank-in-preamble-*. The whole preamble is contiguous.

Every validator category maps to exactly one mechanical fix. Apply verbatim.

ScriptCategoryFix
audit-strictmissing-doc, missing-type, set-mutator, abstract-or-virtual-originRead the member body, then add <summary> + <param>/<returns>/<typeparam> as applicable
audit-strictmisplaced-above-*Move the offending [attr] / #if / // ReSharper once line below the /// block
audit-strictno-blank-above-*Insert one blank line above the /// block
audit-strictblank-in-preamble-*Remove the blank line(s) between the block and the declaration
audit-strictunrequired-* (override, explicit-iface, implicit-iface, private, internal, in-non-external-type)Delete the /// block
doc-qualityparam-missingAdd <param name="…"> per real parameter, description grounded in the body
doc-qualitytypeparam-missingAdd <typeparam name="…"> per generic type parameter
doc-qualityparam-undefined, typeparam-undefinedRemove the phantom tag — the name matches no parameter (usually a renamed/removed arg)
doc-qualityparam-empty, typeparam-emptyFill the body — <param name="x"/> and <param name="x"></param> both count as empty, as does a body containing only <see cref=…/>
doc-qualityname-restatement, filler-only, echo-getter, empty-summaryRewrite — the summary must say something the identifier does not
doc-qualitysignature-dumpThe summary is a verbatim C# declaration (prior-agent corruption). Replace with prose

set-mutator is called out separately because public SetX(...) methods added in commits adjacent to a docs pass are the single most common blind spot. Take those rows seriously.

  • Read the implementation before drafting. Never describe what a member “probably” does from its name. Confabulating from name patterns is the named failure mode that damaged a prior fan-out.
  • Say something the identifier doesn’t. doc-quality.py mechanically rejects a summary that normalizes to the member name, or whose every word is filler + name tokens. /// <summary>Awake.</summary> on Awake() → name-restatement. /// <summary>Hides the cheat container until the unlock gesture is detected.</summary> → passes.
  • Direct active voice. “Returns…”, “Computes…”, “Publishes…” — not “This method returns…”.
  • No filler <remarks>. If it would rephrase the <summary>, omit it.
  • Cross-asmdef references use <c>TypeName</c>, not <see cref="…"/>. An unresolvable cref becomes a silent gap in downstream metadata builds; <c> always renders.

Pattern-specific handling (async/UniTask, generics, ref-count APIs, reflection, define-gated members, [Obsolete]): references/pattern-handling-and-provenance.md.

Workflow — documenting a package or submodule

Section titled “Workflow — documenting a package or submodule”
  1. Baseline — run both validators on the whole target and record the row counts. This is the number you must drive to zero, and it tells you the shape of the work (missing summaries vs param-missing bulk vs placement noise).
  2. Enumerate asmdefs (find <root> -name '*.asmdef') and work smallest/lowest-risk → largest. Typical order: DI/registration → models → editor → services → views → gameplay.
  3. Pre-pass triage grep per asmdef so reviewers know where to look hardest:
    Terminal window
    grep -rn "reflection\|\.GetType()\|Activator\." <asmdef-path>
    grep -rn "async\|UniTask\|CancellationToken" <asmdef-path>
    grep -rn "where T " <asmdef-path>
    grep -rn "\[Obsolete" <asmdef-path>
  4. Edit — apply the scope rules + playbook.
  5. Validate the asmdef — both scripts, zero rows, before committing.
  6. Commit with the pathspec form (never git add . / -A / git commit -a):
    Terminal window
    git commit -m "docs(<asmdef>): add XML doc comments" -- <asmdef-path>/
    One branch for the whole repo (docs/api-docs-setup or docs/xml-gapfill), one commit per asmdef. Never one branch per asmdef.
  7. Final full-repo validation — re-run both on the repo root. Members added in commits adjacent to your pass only show up here, not in the per-asmdef runs.
  8. One PR per repo. Include the per-asmdef file/line table, the triage-grep counts, any uncertainty flags, and the pasted validator output showing summary: 0.

For a large target, chunk by asmdef group and commit at each boundary — never leave a half-documented asmdef uncommitted across a budget checkpoint.

  • Piping masks the exit code. python3 audit-strict.py . | tail -5 reports tail’s status, so a failing run looks green. Check the row count in the summary: line, or use ${PIPESTATUS[0]} / run unpiped when you need the exit code in a gate.
  • Before v3.4.0 a single-file argument silently false-greened. Both scripts expanded their argument with rglob("*.cs") unconditionally, so a .cs file path matched zero files and printed summary: 0 … with exit 0 — identical to a real pass. Fixed in 3.4.0, which also added the scanned: count so the failure mode is visible rather than silent. If you are on an older copy, pass the containing directory, never a file.
  • summary: 0 missing-or-misplaced / 0 unrequired is the only passing audit-strict line. Both halves must be zero — the second half is the delete-these-docs half.
  • doc-quality.py reports several rows per member (one per undocumented param). Row count is not member count; a single method with 4 params contributes 4 rows.
  • Constructors and public fields are in scope. Both validators flag them; they are easy to miss when scanning for “methods”.
  • #if-guarded alternate declarations — the doc lives above the first branch only. The auditor will not ask you to duplicate it into the #else branch.
  • Editor asmdefs are normal scope. No filter override — internal editor tooling is skipped naturally by the visibility rules, genuinely public editor API is documented.
  • Doc comments are comment-only: zero IL, runtime, or compile impact. Rollback is reverting one commit. This is why an all-at-once pass is safe and per-file verification is wasted effort — batch the edits, validate once at the end.
  • Suspected false positive? Report it — do not mangle source to satisfy the script. The auditors have accumulated verified fixes (single-line-attribute declarations, single-line-getter signature truncation, operator-overload param parsing, #if-guarded params); a genuinely new edge case is a script bug worth fixing at the source.

theonekit-core ships two hooks that run these same validators for you. They are advisory — the manual gate above stays the authoritative done-check.

HookFires onBehaviour
doc-drift-nudgePostToolUse — Edit / Write / MultiEdit of a .cs fileValidates that one file. On rows > 0, emits a [t1k:doc-drift …] block listing them and directing the assistant to activate this skill. Silent when clean.
doc-drift-commit-gatePreToolUse — a Bash git commitValidates the staged .cs set, prints a report to stderr, and still allows the commit (warn-only by design).
  • Bypass the commit warning: T1K_SKIP_DOC_GATE=1 git commit … (the inline prefix form is required — hooks do not see the bash subprocess’s environment).
  • Both hooks go fully dormant when this skill is not installed, and each nudges once per drift-signature per session rather than on every keystroke.
  • They need this skill at ≥ 3.4.0. Against an older copy the hooks emit a one-time “update theonekit-unity” notice instead of a drift report — deliberately, because an older copy would return zero rows for every file and look permanently clean.

→ references/validator-categories.md for the full category reference, detection heuristics, and what each script deliberately does not flag. → references/pattern-handling-and-provenance.md for where the two scripts came from and which repos already went through this pass.