typescript-advanced-docs

TypeScript Documentation

Documentation tooling and conventions for TypeScript codebases: JSDoc, TypeDoc, ADRs, and framework-specific patterns.

Mindset

Write documentation that a compiler-checked type can't already express — a JSDoc @param restating a parameter's type the signature already shows is noise; a JSDoc comment explaining why a parameter exists, what invariant it must satisfy, or what happens at its edge cases earns its place. Treat an ADR as a record for a future reader who wasn't in the room, not a justification written for the reviewer who is: state the decision, the alternatives considered, and the consequences accepted, in that order. Generated documentation (TypeDoc output) is only as good as the JSDoc it's generated from — investing in TypeDoc configuration without investing in the comments it reads from produces a well-formatted site with nothing useful in it.

When to Apply

Use this skill when:

• Writing JSDoc comments for a public API surface
• Configuring TypeDoc to generate a documentation site from TypeScript source
• Recording an architectural decision with an ADR
• Documenting a framework-specific pattern (NestJS decorators, React components, Angular/Compodoc)

Use When

• "How should I document this public function/class with JSDoc?"
• "How do I set up TypeDoc to generate our API docs?"
• "How do I write an ADR for this decision?"
• "What's the convention for documenting a NestJS/React/Angular component?"

Scope

In Scope

• JSDoc comment patterns and best practices.
• TypeDoc configuration and setup.
• ADR templates and structure.
• Framework-specific documentation patterns (NestJS, React, Angular).

Out of Scope

• The type-first design decisions an ADR might record — see the sibling typescript-practices skill for the workflow itself.
• Generating documentation content from types mechanically covered elsewhere (e.g. what a mapped type does) — see the sibling typescript-type-system skill for the mechanics; this skill covers how to document the result.