giuseppe-trisciuoglio/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

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

/**
 * 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

# 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

/**
 * 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

/**
 * Validates email addresses using RFC 5322 specification
 *
 * @param email - Email address to validate
 * @returns True if email format is valid
 *
 * @example
 * ```typescript
 * isValidEmail('[email protected]'); // 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

/**
 * 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 — JSDoc patterns for interfaces, functions, classes, generics, and unions
• references/framework-patterns.md — Framework-specific patterns for NestJS, React, Express, and Angular
• references/adr-patterns.md — ADR templates and examples
• references/pipeline-setup.md — CI/CD pipeline configuration for documentation
• references/validation.md — ESLint rules and validation checklists
• references/typedoc-configuration.md — Complete TypeDoc configuration options
• references/examples.md — Additional code examples