TSDoc for TypeScript Interfaces

Documenting TypeScript Interfaces

Interfaces define the shape of objects in TypeScript. A well-documented interface explains what the object represents, when to use it, and what each property means.

Example Signature

interface PaginationOptions {
  page: number;
  limit: number;
  sortBy?: string;
  sortOrder?: "asc" | "desc";
  cursor?: string;
}

Generated TSDoc

/**
 * Configuration options for paginated API queries.
 *
 * @remarks
 * Use cursor-based pagination for large datasets (over 10,000 records).
 * Offset-based pagination (page + limit) is suitable for smaller datasets
 * where users need to jump to specific pages.
 *
 * @example
 * ```typescript
 * const options: PaginationOptions = {
 *   page: 1,
 *   limit: 20,
 *   sortBy: "createdAt",
 *   sortOrder: "desc",
 * };
 * ```
 */

Property-Level Documentation

Each property in the interface can have its own JSDoc comment:

interface PaginationOptions {
  /** The 1-based page number. */
  page: number;
  /** Maximum number of items per page (1-100). */
  limit: number;
  /** Property name to sort by. Omit for default ordering. */
  sortBy?: string;
}

Using @remarks

The @remarks tag in TSDoc separates the brief summary from extended documentation. Tools like API Extractor use this to show summaries in quick-info popups while hiding the remarks section.

Interface vs Type Alias

The documentation approach is the same for both interface and type declarations. The generator produces a class-level comment block that works for either.