Course contentsShow
← TypeScript
Lesson 1684 of 1,79638. Common Patterns and AntipatternsFree lesson

JSDoc Comments for Public APIs

When and how to add JSDoc comments to augment TypeScript types with usage examples and context.

JSDoc Comments for Public APIs

You'll learn: When and how TypeScript developers use JSDoc comments to add usage examples, rationale, and context to public APIs—turning good types into great documentation.

What JSDoc Comments Add to TypeScript

TypeScript's type system already documents what your API accepts and returns. But it doesn't explain why certain parameters exist, when to use a function, or how common use cases work. JSDoc comments fill this gap by adding human-readable documentation that appears in IDE tooltips and generated docs.

Think of types as the "nutrition label" on food packaging—they tell you the ingredients. JSDoc is the recipe on the back—it tells you how to actually use those ingredients.

When to Add JSDoc to Public APIs

You should add JSDoc comments when:

  • The function's purpose isn't obvious from its name and types alone
  • Parameters need context beyond their type (valid ranges, special values, format expectations)
  • Usage examples would help callers understand the common patterns
  • You're publishing a library where consumers won't read your implementation
  • Business rules or constraints exist that types can't express

For private/internal functions, types alone are often sufficient.

Basic JSDoc Syntax with TypeScript

JSDoc comments use /** */ and appear directly above the declaration. TypeScript understands JSDoc tags and shows them in IntelliSense:

/**
 * Converts a user-friendly display name into a URL-safe slug.
 * 
 * Lowercases the input, replaces spaces with hyphens, and removes
 * special characters. Useful for generating readable URLs.
 * 
 * @param displayName - The human-readable name to convert
 * @returns A URL-safe slug (lowercase, hyphenated)
 * 
 * @example
 * ```ts
 * const slug = createSlug("Hello World!");
 * console.log(slug); // "hello-world"
 * ```
 */
function createSlug(displayName: string): string {
  return displayName
    .toLowerCase()
    .replace(/\s+/g, '-')
    .replace(/[^\w-]/g, '');
}

When you hover over createSlug in your editor, you'll see the description, parameter details, and example—all without opening the source file.

JSDoc Augments Types, Not Replaces Them

Don't use JSDoc @param and @returns type annotations when you already have TypeScript types. Let TypeScript's type system be the single source of truth for types, and use JSDoc for context:

// ❌ Redundant: types are duplicated
/**
 * @param id - {string} User identifier
 * @returns {Promise<User>} The user object
 */
async function fetchUser(id: string): Promise<User> {
  // ...
}

// ✅ Better: JSDoc adds information types can't express
/**
 * Fetches a user by their unique identifier.
 * 
 * @param id - Must be a valid UUID v4
 * @throws {NotFoundError} When user doesn't exist
 */
async function fetchUser(id: string): Promise<User> {
  // ...
}

Practical JSDoc Tags for Public APIs

  • @example - Show common usage patterns inline
  • @throws - Document error conditions types don't capture
  • @see - Link to related functions or external resources
  • @deprecated - Mark old APIs with migration guidance
  • @remarks - Add longer explanations or caveats

Key Takeaway: JSDoc comments turn TypeScript's type signatures into complete API documentation by adding usage examples, rationale, and constraints that types alone can't express. Use them for public APIs where callers need context beyond the type signature.