typescript-docs

# 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 ```bash npm install --save-dev typedoc typedoc-plugin-markdown ``` ```json { "entryPoints": ["src/index.ts"], "out": "docs/api", "theme": "markdown", "excludePrivate": true, "readme": "README.md" } ``` ### 2. Add JSDoc Comments ```typescript /** * Service for managing user authentication * * @remarks * Handles JWT-based authentication with bcrypt password hashing. * * @example * ```typescript * const authService = new AuthService(config); * const token = await authService.login(email, password); * ``` * * @security * - Passwords hashed with bcrypt (cost factor 12) * - JWT tokens signed with RS256 */ @Injectable() export class AuthService { /** * Authenticates a user and returns access tokens * @param credentials - User login credentials * @returns Authentication result with tokens * @throws {InvalidCredentialsError} If credentials are invalid */ async login(credentials: LoginCredentials): Promise<AuthResult> { // Implementation } } ``` ### 3. Create an ADR ```markdown # 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 ```yaml 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 ```json { "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 ```typescript /** * Custom hook for fetching paginated data * * @remarks * This hook manages loading states, error handling, and automatic * refetching when the page or filter changes. * * @example * ```tsx * function UserList() { * const { data, isLoading, error } = usePaginatedData('/api/users', { * page: currentPage, * limit: 10 * }); * * if (isLoading) return <Spinner />; * if (error) return <ErrorMessage error={error} />; * return <UserTable users={data.items} />; * } * ``` * * @param endpoint - API endpoint to fetch from * @param options - Pagination and filter options * @returns Paginated response with items and metadata */ export function usePaginatedData<T>( endpoint: string, options: PaginationOptions ): UsePaginatedDataResult<T> { // Implementation } ``` ### Documenting a Utility Function ```typescript /** * Validates email addresses using RFC 5322 specification * * @param email - Email address to validate * @returns True if email format is valid * * @example * ```typescript * isValidEmail('user@example.com'); // true * isValidEmail('invalid-email'); // false * ``` * * @performance * O(n) where n is the email string length * * @see {@link https://tools.ietf.org/html/rfc5322} RFC 5322 Specification */ export function isValidEmail(email: string): boolean { const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; return emailRegex.test(email); } ``` ### NestJS Controller Documentation ```typescript /** * REST API endpoints for user management * * @remarks * All endpoints require authentication via Bearer token. * Rate limiting: 100 requests per minute per user. * * @example * ```bash * curl -H "Authorization: Bearer <token>" https://api.example.com/users/123 * ``` * * @security * - All endpoints use HTTPS * - JWT tokens expire after 1 hour * - Sensitive data is redacted from logs */ @Controller('users') export class UsersController { /** * Retrieves a user by ID * @param id - User UUID * @returns User profile (password excluded) */ @Get(':id') async getUser(@Param('id') id: string): Promise<UserProfile> { // Implementation } } ``` ## Best Practices 1. **Document Public APIs**: All public methods, classes, and interfaces 2. **Use `@example`**: Provide runnable examples for complex functions 3. **Include `@throws`**: Document all possible errors 4. **Add `@see`**: Cross-reference related functions/types 5. **Use `@remarks`**: Add implementation details and notes 6. **Document Generics**: Explain generic constraints and usage 7. **Include Performance Notes**: Document time/space complexity 8. **Add Security Warnings**: Highlight security considerations 9. **Keep Updated**: Update docs when code changes 10. **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 - **[references/jsdoc-patterns.md](references/jsdoc-patterns.md)** — JSDoc patterns for interfaces, functions, classes, generics, and unions - **[references/framework-patterns.md](references/framework-patterns.md)** — Framework-specific patterns for NestJS, React, Express, and Angular - **[references/adr-patterns.md](references/adr-patterns.md)** — ADR templates and examples - **[references/pipeline-setup.md](references/pipeline-setup.md)** — CI/CD pipeline configuration for documentation - **[references/validation.md](references/validation.md)** — ESLint rules and validation checklists - **[references/typedoc-configuration.md](references/typedoc-configuration.md)** — Complete TypeDoc configuration options - **[references/examples.md](references/examples.md)** — Additional code examples