TSDoc for TypeScript Utility Types and Mapped Types

Documenting Utility and Mapped Types

TypeScript utility types perform transformations on other types. Documenting them is critical because the logic is often non-obvious from the type definition alone.

Example Signature

type DeepReadonly<T> = {
  readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
};

Generated TSDoc

/**
 * Recursively makes all properties of T readonly.
 *
 * Unlike the built-in `Readonly<T>` which only affects top-level
 * properties, `DeepReadonly` traverses nested objects to make every
 * property at every depth level immutable.
 *
 * @typeParam T - The source type to make deeply readonly.
 *
 * @example
 * ```typescript
 * interface Config {
 *   db: { host: string; port: number };
 *   cache: { ttl: number };
 * }
 *
 * const config: DeepReadonly<Config> = loadConfig();
 * config.db.host = "new"; // Error: readonly property
 * ```
 */

What to Include

1. Summary: What the type does in one sentence
2. Comparison: How it differs from built-in or similar types
3. Type parameters: What each type parameter represents
4. Example: A concrete usage example showing the type in action
5. Caveats: Edge cases like circular references, union types, or primitives

Common Utility Type Patterns

Pattern	Tags to include
Mapped type ({ [P in keyof T]: ... })	@typeParam, example
Conditional type (T extends U ? X : Y)	@typeParam, explanation of branches
Template literal type	@typeParam, pattern description
Intersection/union helper	@typeParam, comparison with alternatives