JSDoc for Rest Parameters and Variadic Functions

Documenting Rest Parameters

Rest parameters allow functions to accept an indefinite number of arguments. The documentation should explain what each argument represents and any minimum count requirements.

Example Signature

function merge<T extends Record<string, unknown>>(
  target: T,
  ...sources: Partial<T>[]
): T

Generated JSDoc

/**
 * Deep merges one or more source objects into a target object.
 * Properties from later sources overwrite earlier ones.
 *
 * @template T - The shape of the target and source objects.
 * @param {T} target - The object to merge into. This object is mutated.
 * @param {...Partial<T>[]} sources - One or more source objects whose
 *   properties will be merged into the target. Applied left to right.
 * @returns {T} The mutated target object with all sources merged in.
 *
 * @example
 * ```typescript
 * const defaults = { color: "blue", size: 12, bold: false };
 * const userPrefs = { color: "red" };
 * const override = { bold: true };
 * const result = merge(defaults, userPrefs, override);
 * // { color: "red", size: 12, bold: true }
 * ```
 */

Rest Parameter Syntax in JSDoc

Use the spread operator in the param tag:

@param {...string[]} args - The string arguments to concatenate.

Tuple Rest Types

TypeScript supports typed tuple rest parameters:

function log(level: string, ...args: [message: string, ...data: unknown[]])

Document each tuple position:

@param {...[string, ...unknown[]]} args - The first element is the message
  string, followed by optional data values for interpolation.

Minimum Argument Requirements

If the function requires at least one rest argument, state this in the description or use @throws to document what happens when no arguments are provided.