Documenting With Tsdoc

TSDoc vs JSDoc

Key Difference: TSDoc is TypeScript-first. JSDoc type annotations are redundant in TypeScript.

❌ Don't Use JSDoc Types in TypeScript

/**
 * @param {string} id - User ID (REDUNDANT - TypeScript has the type)
 * @returns {Promise<User | null>} (REDUNDANT)
 */
export async function getUser(id: string): Promise<User | null> {
  // ...
}

✅ Use TSDoc Syntax Instead

/**
 * Retrieves a user by their unique identifier.
 *
 * @param id - The user's unique identifier
 * @returns The user object or null if not found
 */
export async function getUser(id: string): Promise<User | null> {
  // ...
}

Why: TypeScript's type system already provides type information. TSDoc focuses on describing behavior, not duplicating types.

Basic TSDoc Syntax

Minimal Doc Comment

/**
 * Calculates the total price including tax.
 */
export function calculateTotal(price: number, taxRate: number): number {
  return price * (1 + taxRate);
}

Complete Doc Comment

/**
 * Retrieves a user by their unique identifier.
 *
 * @remarks
 * This method queries the database and caches the result for 5 minutes.
 * Use {@link invalidateUserCache} to clear the cache manually.
 *
 * @param id - The user's unique identifier
 * @returns The user object or null if not found
 *
 * @throws {@link NotFoundError}
 * Thrown when the user ID doesn't exist in the database
 *
 * @throws {@link DatabaseError}
 * Thrown when the database connection fails
 *
 * @example
 * Basic usage:
 * ```typescript
 * const user = await getUser('abc123');
 * if (user) {
 *   console.log(user.name);
 * }
 * ```
 *
 * @example
 * With error handling:
 * ```typescript
 * try {
 *   const user = await getUser('abc123');
 * } catch (error) {
 *   if (error instanceof NotFoundError) {
 *     console.log('User not found');
 *   }
 * }
 * ```
 *
 * @public
 */
export async function getUser(id: string): Promise<User | null> {
  // Implementation
}

Common TSDoc Tags

For complete tag reference, see: references/tsdoc-tags.md

Linking

Link to Another Symbol

/**
 * Creates a new user.
 *
 * @remarks
 * Use {@link updateUser} to modify existing users.
 * Use {@link deleteUser} to remove users.
 *
 * @see {@link UserService.validateUser} for validation logic
 */
export function createUser(data: CreateUserDTO): User {
  // ...
}

Link to External Documentation

/**
 * Implements OAuth 2.0 authentication.
 *
 * @remarks
 * See the official specification: {@link https://oauth.net/2/ | OAuth 2.0}
 * For implementation details: {@link https://docs.example.com/auth | Auth Guide}
 */
export class OAuthProvider {
  // ...
}

TypeDoc Generation

Installation

# Install TypeDoc as dev dependency
npm install -D typedoc

# Verify installation
npx typedoc --version

Basic Usage

# Generate HTML documentation
npx typedoc --entryPoints src/index.ts --out docs

# Generate JSON (for custom documentation sites)
npx typedoc --json docs/api.json

# Watch mode (regenerate on file changes)
npx typedoc --watch

TypeDoc Configuration

Create typedoc.json in your project root:

{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "excludePrivate": true,
  "excludeInternal": true,
  "excludeProtected": false,
  "categorizeByGroup": true,
  "defaultCategory": "Other",
  "categoryOrder": ["Core", "Utilities", "Types", "*"],
  "readme": "README.md",
  "theme": "default",
  "includeVersion": true
}

For advanced TypeDoc configuration, see: references/typedoc-config.md

Integration with npm Scripts

Add to package.json:

{
  "scripts": {
    "docs": "typedoc",
    "docs:json": "typedoc --json docs/api.json",
    "docs:watch": "typedoc --watch"
  }
}

Then run:

npm run docs          # Generate HTML docs
npm run docs:json     # Generate JSON
npm run docs:watch    # Watch mode

Documentation Best Practices

1. Document All Public Exports

// ✅ GOOD: Public function has documentation
/**
 * Validates user input before processing.
 *
 * @param input - User-provided data
 * @returns True if valid, false otherwise
 * @public
 */
export function validateInput(input: unknown): boolean {
  // ...
}

// ❌ BAD: Public function lacks documentation
export function processData(data: any): void {
  // No documentation
}

2. Include at Least One Example

/**
 * Formats a date according to locale settings.
 *
 * @param date - The date to format
 * @param locale - Locale code (e.g., 'en-US', 'fr-FR')
 * @returns Formatted date string
 *
 * @example
 * ```typescript
 * const formatted = formatDate(new Date(), 'en-US');
 * console.log(formatted); // "12/31/2023"
 * ```
 *
 * @public
 */
export function formatDate(date: Date, locale: string): string {
  return date.toLocaleDateString(locale);
}

3. Use @remarks for Implementation Details

/**
 * Caches API responses for improved performance.
 *
 * @remarks
 * This cache uses an LRU strategy with a maximum size of 100 entries.
 * Entries expire after 5 minutes. Use {@link clearCache} to manually
 * invalidate all cached entries.
 *
 * @internal
 */
class ResponseCache {
  // ...
}

4. Link to Related Functions

/**
 * Creates a new user account.
 *
 * @see {@link updateUser} - Modify existing users
 * @see {@link deleteUser} - Remove user accounts
 * @see {@link findUser} - Look up users
 *
 * @public
 */
export function createUser(data: UserData): User {
  // ...
}

5. Mark Internal APIs with @internal

/**
 * Internal utility for validating email formats.
 *
 * @remarks
 * This function is used internally by {@link createUser} and {@link updateUser}.
 * External callers should use the public validation API instead.
 *
 * @internal
 */
export function _validateEmail(email: string): boolean {
  // ...
}

For complete best practices, see: references/documentation-best-practices.md

Common Mistakes to Avoid

See: references/common-mistakes.md

• Duplicating type information from TypeScript signatures
• Missing @example blocks
• Verbose descriptions that just restate the code
• Inconsistent documentation across API surface
• Forgetting to mark internal APIs with @internal

Advanced Patterns

See: references/advanced-patterns.md

• Documenting generic types
• Complex @throws scenarios
• Module-level documentation
• Grouping APIs with @category
• Custom TypeDoc themes

Related Skills

• structuring-hexagonal-typescript - Architecture that benefits from clear API documentation
• validating-with-zod-schemas - Schema validation often needs API documentation
• typescript-advanced - Advanced TypeScript patterns that should be documented

References

Official Documentation:

• TSDoc Specification
• TypeDoc Documentation
• TypeDoc Configuration

Additional Resources:

• Cloudflare TypeScript Docs Guide
• TSDoc Playground