iru-typescript-tsdoc
Audit given TypeScript file(s)/scope for complete TSDoc coverage on every exported function, class, interface, type alias, and enum (React components' props interfaces and hooks, Angular components/se
SKILL.md.claude/skills/iru-typescript-tsdoc/SKILL.md
GitHubTypeScript TSDoc
Make sure a set of TypeScript files carry complete, well-formed TSDoc on every exported symbol, filling in
whatever is missing, then prove the result actually builds via the project's own doc tooling (TypeDoc or
Compodoc). This skill only adds/completes documentation comments — it does not change behavior, signatures, or
non-comment code. Test files (*.test.ts(x), *.spec.ts(x), anything under test/, tests/, __tests__/, or
e2e/) are out of scope for documentation requirements — they don't need TSDoc added, even if named explicitly —
but any TSDoc a test file already has must be left as-is; never strip or "clean up" existing comments in test
code. It makes no assumptions about this being any particular repository — discover the project's actual flavor,
conventions, and build setup fresh each run.
Step 0 — Detect the project's flavor
Framework detection rule (shared with every other skill in this catalog's TypeScript group — apply the same checks here so the doc bar and verification command match what the rest of the pipeline assumes):
@vaadin/hilla/hilla-spring-boot-starterinpom.xml, or asrc/main/frontend/directory → hilla-frontendexpoorreact-nativeinpackage.jsondependencies → react-native — toolchain expo whenexpois a dependency (even withandroid//ios/present asnpx expo prebuildoutput), otherwise metro (bare React Native CLI app; Expo also bundles with Metro — the name only distinguishes the two toolchains)@ionic/angularor@ionic/react+@capacitor/coreinpackage.json→ ionic@nestjs/coreinpackage.json→ nestjsnextinpackage.json→ nextjs@angular/coreinpackage.json→ angularreact+viteinpackage.json→ react- none of the above → library
This drives two things later: which build tool verifies the docs (Step 5 — Compodoc for angular, TypeDoc for
every other flavor except nestjs/nextjs/react-native, which use whichever tool the project actually
configured, or none) and what "exported" means for the audit (Step 1).
Doc tool for nestjs/nextjs — these app flavors often ship no doc tool at all, so never fetch one on the fly
with a bare npx typedoc/npx compodoc (that downloads and runs a tool the project never chose):
- nestjs: Compodoc is the de-facto Nest documentation tool (it understands modules, controllers, providers,
and routes) — use it when
@compodoc/compodocis a devDependency or a.compodocrc*/compodocscript exists. Otherwise use TypeDoc whentypedocis a devDependency or atypedoc.jsonexists. Neither → audit-only. - nextjs: TypeDoc when
typedocis a devDependency or atypedoc.jsonexists; otherwise audit-only. - react-native (both toolchains): same rule as nextjs — TypeDoc only when
typedocis a devDependency or atypedoc.jsonexists (neither the React Native CLI template norcreate-expo-appships one); otherwise audit-only. - Audit-only means Steps 1-4 still run in full (the audit and the generated TSDoc don't depend on a build tool), Step 5 is skipped, and the Step 6 report says "doc build not verified: no TypeDoc/Compodoc configured in this project" — never a pass.
Step 1 — Determine scope
- Argument provided (comma-separated paths or globs): resolve each to its file(s) via
find/ls. Drop any resolved file that is a test file per the definition above — say so in the Step 6 report rather than silently ignoring it, since test files carry no TSDoc requirement here. - No argument: default to every non-test
.ts/.tsxfile touched by uncommitted changes plus commits on the current branch not yet on the base branch, same approach asiru-update-docs:
(determine the base branch viagit status git diff <base-branch>...HEAD --name-only git diff --name-onlygit symbolic-ref refs/remotes/origin/HEADorgit branch -aif unclear; ask the user only if genuinely ambiguous). Filter outnode_modules/,dist/,build/, generated files (src/main/frontend/generated/for Hilla,.d.tsfiles), and non-TypeScript files. - If the resulting scope is empty (no argument and no relevant changes), tell the user there is nothing to document and stop.
- What "exported" means, per flavor (this defines the audit set within each in-scope file):
- library: every symbol reachable from the package's public entry point (
src/index.tsor whateverpackage.json'sexports/main/typesfields name) — an exported symbol re-exported fromindex.tscounts even if the file itself is not directly in scope; a symbol exported from a file but never re-exported from the entry point is still in scope if its file is in scope (it's still part of that file's API surface for anyone importing it directly) but is lower priority for@example(Step 3). - react / react-native / ionic / hilla-frontend (apps): simply every
exported function, class, interface, type alias, and enum in each in-scope file — there is no single public entry point to trace, since app code is consumed by the bundler, not by external importers. - react-native specifics (both toolchains): screens/components (a one-line summary of what the screen
renders, plus its props type — React Navigation screens'
route.paramsshape, Expo Router routes' search params), hooks, and services are in scope; so is a Turbo Module/Codegen spec (Native*.tsexportinginterface Spec extends TurboModule) — document each method with what the native side does, its@params, and the promise's resolve/reject contract, since the TypeScript spec is the only shared contract between the JS and the Kotlin/Obj-C++ implementations. Never in scope: anything underandroid/,ios/,.expo/,node_modules/;metro.config.js,babel.config.js,react-native.config.js,app.config.*,jest.config.*; and the rootindex.js/index.tsthat only callsAppRegistry.registerComponent/registerRootComponent— drop them from the scope like test files and say so in the report. An Expo Router_layout.tsx/route file's default export gets a one-line summary and never an@example. - nestjs: every exported class in scope by its Nest role — controllers (
@Controller: the class, plus every route-handler method with what the endpoint does, a@paramper@Param()/@Query()/@Body()argument,@returnsdescribing the response body, and@throwsperHttpExceptionsubclass it can raise —NotFoundException,ConflictException, …), services/providers/repositories (@Injectable: class and public methods), DTOs (the class and each property, stating its validation constraints in words where theclass-validatordecorators make them non-obvious), modules (@Module: a class-level comment saying what the feature module provides and exports — Compodoc lists modules as their own pages), guards, pipes, interceptors, filters, and custom decorators (class/factory pluscanActivate/transform/intercept/catch), entities/schemas, and exported interfaces/types/enums. Compodoc also counts the non-exportedbootstrapfunction insrc/main.ts(verified on a Nest 12 scaffold: it was listed as0 % for file src/main.ts - bootstrap - under minimum per file) — give it a one-line comment whenmain.tsis in scope and Compodoc is the verifier. - nextjs: every exported component (including the default-exported
page.tsx/layout.tsx/template.tsx/loading.tsx/error.tsx/not-found.tsxcomponents — a one-line summary of what the route renders), its props type, every exported custom hook in'use client'files, every server action exported from a'use server'file or defined inline (inputs, the authentication/authorization it performs, what it revalidates/redirects to, and@throws/the error state it returns), every route handler exported fromroute.ts(GET/POST/…: the request it accepts,ctx.paramsroute parameters, response status codes and body),generateMetadata/generateStaticParams, and exported library functions underlib/. Route-segment config exports (dynamic,revalidate,runtime,fetchCache,metadataobjects, aproxy.ts/middleware.tsconfigmatcher) need at most a one-line comment and never an@example. Skipnext.config.*,next-env.d.ts, and.next/. - angular: every exported class (
@Component,@Injectable,@Directive,@Pipe), its public@Input()/@Output()members and public methods, and every exported interface/type/enum in scope — Compodoc's coverage percentage (Step 5) counts components, services, inputs, and outputs the same way it counts plain classes, so the manual audit here must match that scope or the two checks will disagree.
- library: every symbol reachable from the package's public entry point (
Step 2 — Discover this project's actual TSDoc bar before auditing
Don't assume a fixed documentation scope — discover it from the project itself:
- Check for a contributor guide (
CLAUDE.md,AGENTS.md, a top-levelREADME, or aCONTRIBUTINGfile) for any stated TSDoc convention. - Check
typedoc.json(or thetypedockey inpackage.json) fortreatWarningsAsErrorsandrequiredToBeDocumented(used verbatim as a config key — a JSON array of reflection kind names, e.g.["Class", "Interface", "Function", "TypeAlias", "Enum"]) and forvalidation.notDocumented— verified locally: TypeDoc 0.28.20 does not warn about undocumented exports by default, even with--treatWarningsAsErrorsset.validation.notDocumentedmust be explicitlytrue(CLI:--validation.notDocumented true) for TypeDoc to flag a symbol with no doc comment at all; without it,typedoc --emit none --treatWarningsAsErrorsexits0against a completely undocumented file. If the project's owntypedoc.jsondoesn't setvalidation.notDocumented, still audit for missing docs manually in Step 3 — don't rely on the project's own config to have caught what this skill is here to catch. - Check for
eslint-plugin-jsdocoreslint-plugin-tsdocrules ineslint.config.js(flat config) —jsdoc/require-jsdoc,jsdoc/require-param,jsdoc/require-returns,tsdoc/syntaxset to"error"for exported members raise the bar; note their exact rule ids and severities, they matter foriru-typescript-code-qualityagreeing with what this skill just fixed. - For Angular, check
.compodocrc.json(or acompodockey inpackage.json) forcoverageTest/coverageMinimumPerFile; if absent, the default threshold Compodoc itself uses is 70 % (Step 5 still runs this skill's own request, typically 80 %, matching the group's own convention below unless the project states otherwise). - If none of the above give a clear answer, skim 2-3 existing exported symbols near the ones in scope to see
empirically whether the project already writes full TSDoc (with
@param/@returns) or only summary lines — treat that observed practice as the bar. - Reconcile any conflict between a stated/configured convention and the actually-enforced/observed one by following the stricter of the two, so this skill's output would pass the project's own lint/doc-build checks.
Skim a couple of existing, well-documented exports in the project (prefer ones structurally similar to what's in
scope — a hook if auditing a hook, a service if auditing a service) to internalize the exact phrasing and tag
style before writing new TSDoc: person and tense used, whether summary sentences end in a period, how generic
type parameters are documented, whether @remarks is used for longer explanation versus a plain paragraph after
the summary, and the @param/@returns/@throws ordering. If the project has no existing TSDoc to learn from,
fall back to standard TSDoc convention:
@param name - description— TSDoc uses a hyphen before the description and no{type}annotation (the type already comes from the TypeScript signature); this is the one point where TSDoc differs visibly from classic JSDoc (@param {type} name description). Never write the JSDoc form in a TSDoc-audited project.@returns(not the JSDoc@return) — one sentence describing the returned value; omitted forvoid/Promise<void>.@throws— one per distinct error/exception type that can propagate out, only when the implementation actually throws or explicitly documents a promise rejection reason.@remarks— a paragraph of additional detail beyond the one-line summary, when the summary alone isn't enough (design rationale, caveats, performance notes) — keep the first line a single concise summary regardless.@example— a fenced```tscode block showing realistic usage; required on every public entry point (a library'sindex.tsexports, an app's exported hooks/components used by more than one caller) per the invocation form's own requirement; optional elsewhere.@public/@internal— mark the intended visibility only where the project already does this consistently (common in library flavor to distinguish the stable API surface from implementation details still exported for internal reasons); don't introduce the convention into a project that doesn't already use it.@deprecated— carried over verbatim from an existing comment being extended; never add it new — that's a decision only the code owner makes.{@link OtherSymbol}— use for cross-references instead of a bare name in backticks when pointing at another exported symbol in the same package; TypeDoc'svalidation.invalidLink(when enabled) fails the build on a{@link}that doesn't resolve, so only add one where the referenced symbol actually exists and is exported.
Step 3 — Audit each in-scope file
Read the full file, then check every symbol that counts as "exported" per Step 1's per-flavor definition has a
non-empty /** ... */ doc comment that actually describes its purpose (not just restates its name), scoped per
the bar established in Step 2:
- Functions (including arrow-function exports and custom hooks —
useXyz):@paramper parameter,@returnsunlessvoid,@throwsfor any error path the implementation can actually take. - Classes: a doc comment on the class itself; its exported/public constructor and public methods each with
their own
@param/@returns/@throws; public andprotectedfields with a one-line comment. Angular services (@Injectable) and components (@Component) follow this same shape. - Interfaces and type aliases: a doc comment on the type itself. For a React component's props interface,
document the interface and, where a prop's purpose isn't obvious from its name/type alone, a one-line comment
above that individual prop. For an Angular component's class, document each
@Input()/@Output()member the same way — Compodoc's coverage counts each of these as its own documentable symbol. - Enums: a doc comment on the enum itself and on each member whose meaning isn't self-evident from its name.
- Re-exports (
export { Foo } from './foo',export * from './foo'): no comment needed on the re-export line itself — the documentation requirement lives on the original declaration, which is either already in scope or covered by a different file's audit.
For each item found incomplete or missing entirely, record: the symbol, its kind, what's missing (whole comment
vs. a missing @param/@returns/@throws/@example), and the file it's in.
Step 4 — Generate the missing TSDoc
For every gap found in Step 3, write the TSDoc directly grounded in:
- The symbol's actual implementation (parameter usage, return expression, thrown/rejected errors, a component's actual rendered output or a hook's actual returned value) — read the function/class body, don't infer purely from the signature/name.
- Any current uncommitted/branch changes to that symbol (
git diff/git log -pfor that file/hunk if it was just added or modified) — if the change altered behavior, the new TSDoc must describe the current behavior, not stale prior behavior a name alone might suggest. - The phrasing and tag conventions gathered in Step 2 — match voice, tense, and tag style exactly so the new
comments are indistinguishable from hand-written ones in this codebase, and use the TSDoc hyphen form for
@param, never the JSDoc{type}form.
Apply the edits with the Edit tool. Do not modify code logic, signatures, formatting outside the added comments, or reorder members — this skill only adds/completes TSDoc comments.
Step 5 — Verify the docs actually build
Which tool verifies depends on the flavor detected in Step 0.
library / react / ionic / hilla-frontend (and nestjs / nextjs / react-native when TypeDoc is configured) — TypeDoc
npx typedoc --emit none --treatWarningsAsErrors --validation.notDocumented true
--emit noneskips writing the HTML site — this only needs TypeDoc's own analysis/validation pass, not a full docs build, mirroring how the Java Javadoc skill runsmvn javadoc:jarrather than a full site build.- A repository with no valid
origingit remote makes this command fail for a non-doc reason (verified in a smoke test against a generated library): TypeDoc warnsThe provided git remote "origin" was not validwhile resolving source links, and--treatWarningsAsErrorsturns that into a non-zero exit even when every export is documented. Checkgit remote get-url originfirst; if it fails, append--disableGit --disableSources(verified in the same smoke test:--disableGitalone fails differently —disableGit is set, but sourceLinkTemplate is not, so source links cannot be produced, exit 4 — because TypeDoc still tries to emit source links;--disableSourcesdrops them) so the exit code reflects documentation warnings only, and say so in the Step 6 report. --validation.notDocumented truemust be passed even if the project's owntypedoc.jsondoesn't set it — verified locally that without it,--treatWarningsAsErrorsalone does not catch an entirely undocumented export (exit0); with it, TypeDoc warns per symbol, e.g.undocumentedAdd (CallSignature), defined in <pkg>/src/index.ts, does not have any documentation, and exits non-zero once warnings are treated as errors. If the project's ownrequiredToBeDocumentednarrows which kinds are checked (e.g. excludesProperty), honor that instead of the tool's full default kind list — pass it through via the project's owntypedoc.jsonrather than overriding it, since Step 2 already reconciled it as the effective bar.- TypeDoc needs a resolvable entry point regardless of
--emit none— verified locally: with noentryPointsintypedoc.json/CLI and noexportsfield inpackage.json, TypeDoc warnsNo entry points were provided or discovered from package.json exports, this is likely a misconfigurationand (with--treatWarningsAsErrors) exits non-zero without analyzing anything. TypeDoc can auto-discover the entry point frompackage.json'sexportsmap (verified: anexports: { ".": "./src/index.ts" }field alone was enough, no explicitentryPointsneeded) — this is exactly theexportsmapiru-setup-typescript-librarywrites, so a library scaffolded by this catalog needs no extra flag. For app flavors without a meaningfulexportsmap (react, react-native, ionic, hilla-frontend), pass--entryPointsexplicitly, scoped to the in-scope files themselves, e.g.--entryPoints src/features/foo/useFoo.ts --entryPoints src/features/foo/Foo.tsx, rather than the wholesrc/tree, to keep the run scoped and fast. - nextjs: run
npx next typegenfirst, and add--validation.notExported false. Verified locally on a Next 16.4 scaffold with TypeDoc 0.28 + TypeScript 5.9.3,--entryPointsper in-scope file and--disableGit --disableSources: without typegen, TypeDoc stops onerror TS2304for the globalLayoutPropsroute helper type (it type-checks the project first); after typegen it still warned__global.LayoutProps, defined in .next/types/routes.d.ts, is referenced by ... but not included in the documentation, which--treatWarningsAsErrorsturns into a failure unrelated to any missing comment —--validation.notExported falseremoves exactly that warning while thedoes not have any documentationwarnings foradd, the layout's default export, and itsmetadataexport remained (exit4). - nestjs: point
--entryPointsat the in-scope files exactly as for app flavors above; Nest'stsconfig.jsonalready enablesexperimentalDecorators/emitDecoratorMetadata, which TypeDoc honors. - react-native (both toolchains, only when TypeDoc is configured — Step 0):
--entryPointsper in-scope.ts/.tsxfile, never a directory glob, so nothing underandroid//ios//.expo/and no config or rootindex.js/index.tsfile is ever an entry point. Verified locally with TypeDoc 0.28.20 + TypeScript 6.0.3 on both scaffolds (--entryPoints App.tsxon the React Native CLI 0.87.1 app;--entryPoints App.tsx --entryPoints src/math.tson the Expo SDK 57 app;--disableGit --disableSourcessince neither had anorigin): each undocumented default-exported component was reported asdefault (CallSignature) ... does not have any documentation(exit4), and after adding a one-line comment the metro run exited0. Two things the run depends on beyond the comments themselves:- TypeDoc type-checks the whole
tsconfig.jsonprogram first, test files included — so a type error anywhere stops it with exit3before any doc validation. Verified on the Expo app: with Jest tests present and TypeScript 6'stypes: []default (whichexpo/tsconfig.basedoesn't override), TypeDoc failed onerror TS2593: Cannot find name 'test'in__tests__/App.test.tsx; adding"types": ["jest"]to the app'stsconfig.jsonfixed it (the metro template's@react-native/typescript-configalready sets it). Report such a failure as "TypeDoc blocked by type errors (seeiru-typescript-code-quality)", not as a doc gap — fixing the tsconfig is out of this skill's scope. - Expo's base tsconfig excludes
android/ios; the metro template'sinclude: ["**/*.ts", "**/*.tsx"]only excludesnode_modulesandPods, which is harmless because the native projects hold no TypeScript — but if anandroid//ios/.tsfile ever shows up in a TypeDoc error, it's a tsconfig scoping issue to report, not a file to document. - The TypeDoc 0.28.20 + TypeScript 6.0.3 crash described below did not reproduce on either React Native
scaffold (both ship TypeScript 6.0.3) — still check
npm ls typescript typedocif TypeDoc throws aTypeError.
- TypeDoc type-checks the whole
- Version-compatibility quirk (verified locally, worth checking before trusting a crash for a doc bug):
TypeDoc 0.28.20 crashes outright (
TypeError: Cannot read properties of undefined (reading 'PropertyDeclaration'), not a warning) against a barenpm install typescript's current default (TypeScript 6.0.3), despite 6.0.x being in its declared peer range. Pinningtypescriptto5.9.3resolved it in this verification. If TypeDoc crashes this way, runnpm ls typescript typedocfirst and report the mismatch rather than treating it as an undocumented-symbol issue — it needs a dependency fix, not a doc fix, and is out of this skill's scope to silently "fix" by downgrading a project dependency.
angular (and nestjs when Compodoc is configured) — Compodoc
npx compodoc -p tsconfig.json --silent --coverageTest <threshold> --coverageMinimumPerFile <threshold> --coverageTestShowOnlyFailed
--silent(short form-t) is required to suppress Compodoc's own banner/progress log (an ASCII-art logo plus per-file parse trace) — verified locally this is pure noise the report must not surface; a passing run under--silentprints nothing at all and exits0(no "coverage OK" confirmation line — treat a clean exit code as the pass signal, not the absence of the word "not over threshold").--coverageTest <threshold>(project-wide gate; Compodoc's own default is 70 if omitted) and--coverageMinimumPerFile <threshold>(per-file gate; Compodoc's own default is 0, i.e. off, if omitted) — default both to 80 to match this catalog's coverage convention unless the project's own.compodocrc.jsonstates otherwise (Step 2). A failing run's exit code is non-zero (verified:1) and — this is the useful part — it prints exactly which symbols dragged the file below the per-file minimum, e.g.0 % for file src/index.ts - UndocumentedThing - under minimum per file, which is symbol-level detail, not a raw report dump, safe to forward into the Step 6 report as-is.--coverageTestShowOnlyFailedkeeps the output to failing files/symbols only, which is what keeps this report-only rather than a full coverage listing.--coverageTestThresholdFaildefaults totrue(non-zero exit on failure) — never passfalse, that would turn a real gap into a silent warning.- Compodoc writes its HTML site (default
./documentation/) even in coverage-test mode — pass-d "$TMPDIR/compodoc-out"(or another scratch directory) so the run leaves nothing in the working tree; verified locally on a Nest 12 scaffold that with-dnodocumentation/directory was created and the exit code (1, coverage below threshold) was unchanged. nestjs: same command against the project'stsconfig.json(spec files are left out of the coverage count — verified:app.controller.spec.tswas not listed); the scaffold's own controller, service, andmain.tsbootstrapeach reported0 % ... under minimum per filebefore any TSDoc was added. - Compodoc needs
-p <tsconfig>pointing at atsconfig.jsonthat actually includes the in-scope files (verified locally it runs fine against a plain non-Angulartsconfig.jsontoo, so this same invocation works even before Angular-specific decorators are involved) — if the project has a dedicatedtsconfig.doc.jsonor similar, prefer that.
If either verification fails or warns, fix the offending comment(s) (syntax, a broken {@link}, a missing tag
the project's bar requires) and re-run until it succeeds. A failure naming a symbol outside the current scope
is pre-existing — note it in the report but don't fix it unless the user asks.
Step 6 — Report
Per file in scope, state: how many exported symbols were already fully documented, how many gaps were found and
filled (name each, with its kind), and the final doc-build result (TypeDoc: pass, or the exact warning text and
symbol names that failed; Compodoc: the coverage percentage(s) achieved vs. the threshold, and the per-symbol
lines it reported for anything still under the per-file minimum; audit-only for a nestjs/nextjs/react-native project with
neither tool configured — say so explicitly rather than reporting a pass). If any argument resolved to a test file (Step
1), name it and note it was excluded since test files carry no TSDoc requirement here. If any out-of-scope
pre-existing doc-build failure surfaced in Step 5, mention it separately as a follow-up rather than silently
leaving it out of the report. Never paste the raw TypeDoc/Compodoc console output or generated HTML — report only
the symbol names, tags, and pass/fail result, per this catalog's report-only gate contract (mirrors how
iru-gate-runner expects every doc-comment audit it runs to summarize).
Do not run a full docs-site build beyond what Step 5 needs, fix lint/static-analysis issues unrelated to TSDoc, or add/modify tests — those are a separate quality/implementation skill's job, if this project has one.