| name | typescript-docs |
| description | Generates comprehensive TypeScript documentation using JSDoc, TypeDoc, and multi-layered documentation patterns for different audiences. Use when creating API documentation, architectural decision records (ADRs), code examples, and framework-specific patterns for NestJS, Express, React, Angular, and Vue. |
| allowed-tools | Read, Write, Edit, Bash, Grep, Glob |
TypeScript Documentation
Generate production-ready TypeScript documentation with layered architecture for multiple audiences. Supports API docs with TypeDoc, ADRs, and framework-specific patterns.
Overview
Use JSDoc annotations for inline documentation, TypeDoc for API reference generation, and ADRs for tracking design choices.
Key capabilities:
- TypeDoc configuration and API documentation generation
- JSDoc patterns for all TypeScript constructs
- ADR creation and maintenance
- Framework-specific patterns (NestJS, React, Express, Angular, Vue)
- ESLint validation rules for documentation quality
- GitHub Actions pipeline setup
When to Use
Use this skill when creating API documentation, architectural decision records, code examples, or framework-specific patterns for NestJS, Express, React, Angular, or Vue.
Quick Reference
| Tool | Purpose | Command |
|---|
| TypeDoc | API documentation generation | npx typedoc |
| Compodoc | Angular documentation | npx compodoc -p tsconfig.json |
| ESLint JSDoc | Documentation validation | eslint --ext .ts src/ |
JSDoc Tags
| Tag | Use Case |
|---|
@param | Document parameters |
@returns | Document return values |
@throws | Document error conditions |
@example | Provide code examples |
@remarks | Add implementation notes |
@see | Cross-reference related items |
@deprecated | Mark deprecated APIs |
Instructions
1. Configure TypeDoc
npm install --save-dev typedoc typedoc-plugin-markdown
{
"entryPoints": ["src/index.ts"],
"out": "docs/api",
"theme": "markdown",
"excludePrivate": true,
"readme": "README.md"
}
2. Add JSDoc Comments
@Injectable()
export class AuthService {
async login(credentials: LoginCredentials): Promise<AuthResult> {
}
}
3. Create an ADR
# ADR-001: TypeScript Strict Mode Configuration
## Status
Accepted
## Context
What is the issue motivating this decision?
## Decision
What change are we proposing?
## Consequences
What becomes easier or more difficult?
4. Set Up CI/CD Pipeline
name: Documentation
on:
push:
branches: [main]
paths: ['src/**', 'docs/**']
jobs:
generate-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- run: npm ci
- run: npm run docs:generate
- run: npm run docs:validate
5. Validate Documentation
{
"rules": {
"jsdoc/require-description": "error",
"jsdoc/require-param-description": "error",
"jsdoc/require-returns-description": "error",
"jsdoc/require-example": "warn"
}
}
If validation fails: review ESLint errors, fix JSDoc comments (add missing descriptions, add @param/@returns/@throws where absent), re-run eslint --ext .ts src/ until all errors pass before committing.
Examples
Documenting a React Hook
export function usePaginatedData<T>(
endpoint: string,
options: PaginationOptions
): UsePaginatedDataResult<T> {
}
Documenting a Utility Function
export function isValidEmail(email: string): boolean {
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
return emailRegex.test(email);
}
NestJS Controller Documentation
@Controller('users')
export class UsersController {
@Get(':id')
async getUser(@Param('id') id: string): Promise<UserProfile> {
}
}
Best Practices
- Document Public APIs: All public methods, classes, and interfaces
- Use
@example: Provide runnable examples for complex functions
- Include
@throws: Document all possible errors
- Add
@see: Cross-reference related functions/types
- Use
@remarks: Add implementation details and notes
- Document Generics: Explain generic constraints and usage
- Include Performance Notes: Document time/space complexity
- Add Security Warnings: Highlight security considerations
- Keep Updated: Update docs when code changes
- Don't document obvious code: Focus on why, not what
Constraints and Warnings
- Private Members: Use
@private or exclude from TypeDoc output
- Complex Types: Document generic constraints and type parameters
- Breaking Changes: Use
@deprecated with migration guidance
- Security Info: Never include secrets or credentials in documentation
- Link Validity: Ensure
@see references point to valid locations
- Example Code: All examples should be runnable and tested
- Versioning: Keep documentation in sync with code versions
References