typescript-docs

Generates production-ready TypeScript documentation using JSDoc annotations, TypeDoc for API reference generation, and a layered approach aimed at different audiences. It applies when creating API documentation, architectural decision records, code examples, or framework-specific documentation patterns for NestJS, Express, React, Angular, and Vue.

The workflow combines several tools: inline JSDoc comments on public APIs, TypeDoc to generate API references with Compodoc noted for Angular, and ESLint JSDoc rules to validate documentation quality. A quick-reference section lists the relevant commands and the JSDoc tags it leans on, including param, returns, throws, example, remarks, see, and deprecated. Step-by-step instructions walk through configuring TypeDoc with an entry point and markdown output, adding JSDoc comments with remarks and runnable examples, creating an ADR using a Status, Context, Decision, and Consequences template, setting up a GitHub Actions pipeline that generates and validates docs on pushes to the main branch, and validating with ESLint rules such as require-description, require-param-description, and require-returns-description. When validation fails, the guidance is to fix the flagged JSDoc comments and re-run the linter until it passes before committing.

Worked examples show documenting a React data-fetching hook, a utility function with example and cross-reference tags, and a NestJS controller with security notes. Best practices emphasize documenting public APIs, providing examples for complex functions, recording error conditions, cross-referencing related items, documenting generics and performance characteristics, and focusing comments on why rather than what. Constraints call out excluding private members from output, using deprecation notices with migration guidance, never including secrets in documentation, keeping references valid, and keeping examples runnable. Deeper material lives in linked reference files covering JSDoc patterns for interfaces, functions, classes, generics, and unions; framework-specific patterns; ADR templates; CI/CD pipeline setup; and validation rules. The allowed tools are Read, Write, Edit, Bash, Grep, and Glob, reflecting its file-oriented, command-driven approach to documentation.