t1k:unity:base:documents
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/t1k:unity:base:documentsUnity 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.
The gate
Section titled “The gate”S=.claude/skills/t1k-unity-base-documents/scriptspython3 $S/audit-strict.py <path> [<path> ...] # presence + placement, bidirectionalpython3 $S/doc-quality.py <path> [<path> ...] # content quality + param/typeparam completenessDone = 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.
Scope — what gets a doc block
Section titled “Scope — what gets a doc block”Document (original declarations only):
publictypes and members — types, methods, properties, fields, events, delegates, indexers, operators, constructors, constants — at any nesting depth where the entire enclosing chain is also public (orprotectedinside a public type).protectednon-override members (part of the derived-class contract).protected internalinterface contract members (cross-assembly surface).abstract/virtualdeclarations — these are the origin of the doc.
Skip — and delete the block if one exists (SSOT lives at the origin):
- All
overridemembers, any visibility. The baseabstract/virtualcarries 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.Barcarries 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/internalnested types — e.g.public sealed class Recordinsideprivate sealed class Blueprint. Requires the full enclosing-chain check, not just the member. internal/privatemembers, andprivate/internaltype declarations.
<inheritdoc/> is exempt from the content check — it deliberately defers to the base.
Preamble layout — placement is enforced
Section titled “Preamble layout — placement is enforced”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.Globalpublic float GetMultiplier(int streak) { … }Rules the layout encodes:
- The
///block sits at the top of the preamble. Attributes,#if, and// ReSharper disable oncego below it, never above → otherwisemisplaced-above-*. - One blank line above the block, separating it from the previous member’s
}/;→ otherwiseno-blank-above-*. Not required when the line above opens an outer scope ({,class Foo {), is a#region/#nullable/#pragma warning disabledirective, a// ReSharper disable/restoreregion directive, or a plain//comment. - No blank line between the bottom of the
///block and the declaration → otherwiseblank-in-preamble-*. The whole preamble is contiguous.
Category → fix playbook
Section titled “Category → fix playbook”Every validator category maps to exactly one mechanical fix. Apply verbatim.
| Script | Category | Fix |
|---|---|---|
| audit-strict | missing-doc, missing-type, set-mutator, abstract-or-virtual-origin | Read the member body, then add <summary> + <param>/<returns>/<typeparam> as applicable |
| audit-strict | misplaced-above-* | Move the offending [attr] / #if / // ReSharper once line below the /// block |
| audit-strict | no-blank-above-* | Insert one blank line above the /// block |
| audit-strict | blank-in-preamble-* | Remove the blank line(s) between the block and the declaration |
| audit-strict | unrequired-* (override, explicit-iface, implicit-iface, private, internal, in-non-external-type) | Delete the /// block |
| doc-quality | param-missing | Add <param name="…"> per real parameter, description grounded in the body |
| doc-quality | typeparam-missing | Add <typeparam name="…"> per generic type parameter |
| doc-quality | param-undefined, typeparam-undefined | Remove the phantom tag — the name matches no parameter (usually a renamed/removed arg) |
| doc-quality | param-empty, typeparam-empty | Fill the body — <param name="x"/> and <param name="x"></param> both count as empty, as does a body containing only <see cref=…/> |
| doc-quality | name-restatement, filler-only, echo-getter, empty-summary | Rewrite — the summary must say something the identifier does not |
| doc-quality | signature-dump | The 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.
Writing the summary
Section titled “Writing the summary”- 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.pymechanically rejects a summary that normalizes to the member name, or whose every word is filler + name tokens./// <summary>Awake.</summary>onAwake()→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”- 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-missingbulk vs placement noise). - Enumerate asmdefs (
find <root> -name '*.asmdef') and work smallest/lowest-risk → largest. Typical order: DI/registration → models → editor → services → views → gameplay. - 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> - Edit — apply the scope rules + playbook.
- Validate the asmdef — both scripts, zero rows, before committing.
- Commit with the pathspec form (never
git add ./-A/git commit -a):One branch for the whole repo (Terminal window git commit -m "docs(<asmdef>): add XML doc comments" -- <asmdef-path>/docs/api-docs-setupordocs/xml-gapfill), one commit per asmdef. Never one branch per asmdef. - 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.
- 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.
Hard rules
Section titled “Hard rules”- Piping masks the exit code.
python3 audit-strict.py . | tail -5reportstail’s status, so a failing run looks green. Check the row count in thesummary: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.csfile path matched zero files and printedsummary: 0 …with exit 0 — identical to a real pass. Fixed in 3.4.0, which also added thescanned: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 unrequiredis the only passing audit-strict line. Both halves must be zero — the second half is the delete-these-docs half.doc-quality.pyreports 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#elsebranch.- Editor asmdefs are normal scope. No filter override —
internaleditor tooling is skipped naturally by the visibility rules, genuinelypubliceditor 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.
Automatic drift detection (hooks)
Section titled “Automatic drift detection (hooks)”theonekit-core ships two hooks that run these same validators for you. They are advisory —
the manual gate above stays the authoritative done-check.
| Hook | Fires on | Behaviour |
|---|---|---|
doc-drift-nudge | PostToolUse — Edit / Write / MultiEdit of a .cs file | Validates 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-gate | PreToolUse — a Bash git commit | Validates 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.