TSDoc for TypeScript Generic Functions

Documenting Generic Type Parameters

Generic functions accept type parameters that make them work with multiple types. Documentation should explain what each type parameter represents and any constraints it has.

Example Signature

function groupBy<T, K extends keyof T>(items: T[], key: K): Map<T[K], T[]>

Generated TSDoc

/**
 * Groups an array of items by the value of a specified key.
 *
 * @typeParam T - The type of items in the array.
 * @typeParam K - A key of T to group by.
 * @param items - The array of items to group.
 * @param key - The property name to group items by.
 * @returns A Map where keys are the unique values of the specified
 *   property and values are arrays of items with that value.
 *
 * @example
 * ```typescript
 * const users = [{ dept: "eng", name: "Alice" }, { dept: "eng", name: "Bob" }];
 * const grouped = groupBy(users, "dept");
 * // Map { "eng" => [{ dept: "eng", name: "Alice" }, ...] }
 * ```
 */

@typeParam vs @template

Tag	Standard	When to use
@typeParam	TSDoc	TypeScript projects using TSDoc convention
@template	JSDoc	JavaScript projects or JSDoc-style TypeScript

Documenting Constraints

When a type parameter has a constraint (extends), mention it in the description:

/**
 * @typeParam K - A key of T. Must be a valid property name of the item type.
 */

Multiple Type Parameters

List each type parameter on its own line. Order them as they appear in the signature. Explain the relationship between type parameters when they reference each other.