JSDoc TypeScript Documentation

Expert-level guidance for TypeScript documentation strategy and decision-making.

Documentation Decision Tree

Before Documenting, Ask

Audience: Who will read this?

• Library users (npm package) → Full docs: examples, edge cases, performance, migration guides
• Internal team (company-wide) → Focus on "why" decisions, gotchas, design context
• Future you (personal project) → Context for non-obvious choices, workarounds, TODOs

Value: Does the type system already say it?

• Types say WHAT → Document WHY and WHEN (behavior, constraints, use cases)
• Types unclear → Document WHAT first, then WHY
• Types complete → Skip redundant descriptions, document non-obvious behavior only

Maintenance: Will this stay synchronized?

• Stable contracts (public API) → Document thoroughly, changes require migration guides
• Implementation details → Don't document (will diverge), use code comments instead
• Behavior that changes → Document contract in JSDoc, validate in tests

Critical Anti-Patterns

NEVER: Document What Types Already Express

// NEVER: Completely redundant
/**
 * Gets the user's name.
 * @param user - The user object
 * @returns The user's name as a string
 */
function getName(user: User): string {
  return user.name;
}

Why: Wastes time, adds clutter, becomes outdated. Types already express this contract.

Instead: Only document if there's non-obvious behavior:

/**
 * Gets the user's display name.
 * Falls back to email username if name is not set.
 * Returns "Anonymous" for guest users.
 */
function getDisplayName(user: User): string {
  return user.name || user.email.split('@')[0] || 'Anonymous';
}

NEVER: Skip Error Documentation in Public APIs

// NEVER: Undocumented errors in public function
export async function fetchUser(id: string): Promise<User> {
  // Throws NotFoundError, PermissionError, NetworkError - but not documented!
}

Why: Consumers can't handle errors they don't know about. Leads to unhandled exceptions in production.

Instead: Document ALL possible errors:

/**
 * Fetches user by ID.
 *
 * @throws {NotFoundError} User doesn't exist (404)
 * @throws {PermissionError} Insufficient permissions (403)
 * @throws {NetworkError} Request failed (500)
 */
export async function fetchUser(id: string): Promise<User> {
  // Implementation
}

NEVER: Use Template/Placeholder Documentation

// NEVER: Generic template docs
/**
 * TODO: Add description
 * @param data - The data
 * @returns The result
 */
export function processData(data: any): any {
  // Implementation
}

Why: Worse than no docs—suggests API is documented when it isn't. Misleads users.

Instead: Either document properly or omit JSDoc entirely:

// Better: No docs than bad docs (though still not ideal for public API)
export function processData(data: ProcessInput): ProcessResult {
  // Implementation
}

NEVER: Document Internal Implementation in Public API

// NEVER: Implementation details in public docs
/**
 * Fetches users from Redis cache (primary) or PostgreSQL (fallback).
 * Uses connection pool with 10 max connections.
 * Cache TTL is 5 minutes.
 */
export async function getUsers(): Promise<User[]> {
  // Implementation
}

Why: Locks you into implementation. Users depend on Redis, you can't switch to different cache.

Instead: Document observable behavior only:

/**
 * Fetches all users.
 *
 * @remarks
 * Results may be cached for up to 5 minutes.
 * For real-time data, use {@link getUsersRealtime}.
 */
export async function getUsers(): Promise<User[]> {
  // Implementation
}

NEVER: Skip Migration Guides for Breaking Changes

// NEVER: Breaking change without migration guidance
/**
 * Creates a user.
 *
 * @since 2.0.0
 * @deprecated The API changed in v2.0
 */
export function createUser(data: NewUserData): Promise<User> {
  // What changed? How do I migrate? No guidance!
}

Why: Users can't upgrade without knowing how to migrate.

Instead: Provide explicit migration path:

/**
 * Creates a user.
 *
 * @remarks
 * **Breaking Change in v2.0.0**: `name` parameter moved from top-level
 * to nested under `metadata.name`.
 *
 * Migration:
 * ```typescript
 * // Before (v1.x)
 * createUser({ email, password, name });
 *
 * // After (v2.x)
 * createUser({ email, password, metadata: { name } });
 * ```
 *
 * @since 2.0.0
 */
export function createUser(data: NewUserData): Promise<User> {
  // Implementation
}

NEVER: Use Non-Executable Examples

// NEVER: Pseudocode that doesn't run
/**
 * @example
 * ```typescript
 * // Call the function with parameters
 * myFunction(param1, param2);
 * // Process the result
 * doSomething(result);
 * ```
 */
export function myFunction(a: string, b: number): Result {
  // Implementation
}

Why: Examples that don't run mislead users and break when API changes.

Instead: Use real, executable code:

/**
 * @example
 * ```typescript
 * const result = myFunction('hello', 42);
 * console.log(result.value); // Output: "hello42"
 *
 * // With error handling
 * try {
 *   const result = myFunction('', -1);
 * } catch (error) {
 *   console.error('Invalid input:', error.message);
 * }
 * ```
 */
export function myFunction(a: string, b: number): Result {
  // Implementation
}

When to Load References

Load jsdoc-syntax.md when:

• Need specific JSDoc tag syntax (@param, @returns, @throws, etc.)
• Documenting overloaded functions or complex generics
• Need syntax for React components or classes
• Want comprehensive tag reference

Load library-api-docs.md when:

• MANDATORY: Documenting public library for external consumers
• MANDATORY: Writing documentation for npm package
• Need examples of audience-specific documentation depth
• Documenting breaking changes or deprecations
• Need performance documentation patterns
• Creating migration guides

Load typedoc-setup.md when:

• MANDATORY: Setting up automated documentation generation
• MANDATORY: Configuring TypeDoc for the first time
• Integrating documentation into CI/CD pipeline
• Configuring multi-package monorepo documentation
• Setting up GitHub Pages deployment
• Need documentation validation in pre-commit hooks

Quick Wins: High-Impact Documentation

Focus documentation effort on these high-value targets:

1. Public API functions: 80% of user questions come from public functions
2. Error conditions: Undocumented errors = production incidents
3. Complex types: Generic types and conditional types need explanation
4. Migration guides: Breaking changes without migration = angry users
5. Performance characteristics: O(n²) operations need warnings
6. Examples: One good example > 100 lines of prose

Documentation Smells (Warning Signs)

TypeDoc Validation

Enforce documentation in CI:

// package.json
{
  "scripts": {
    "docs:validate": "typedoc --validation.notDocumented true"
  }
}

Pre-commit hook:

npm run docs:validate || exit 1

Resources

• TypeDoc: https://typedoc.org/
• TSDoc: https://tsdoc.org/ (TypeScript-specific JSDoc standard)
• JSDoc Tags: https://jsdoc.app/