JSDoc for Callback Parameters

Documenting Callback Parameters

When a function accepts a callback as a parameter, the documentation should describe what the callback does, when it is called, and what arguments it receives.

Example Signature

function debounce<T extends (...args: unknown[]) => unknown>(
  fn: T,
  delay: number,
  options?: { leading?: boolean; trailing?: boolean }
): T

Generated JSDoc

/**
 * Creates a debounced version of the provided function that delays
 * invocation until after the specified delay has elapsed since the
 * last call.
 *
 * @template T - The type of the function to debounce.
 * @param {T} fn - The function to debounce. Called after the delay
 *   period with the most recent arguments.
 * @param {number} delay - The debounce delay in milliseconds.
 * @param {object} [options] - Debounce behavior options.
 * @param {boolean} [options.leading=false] - Invoke on the leading
 *   edge of the timeout.
 * @param {boolean} [options.trailing=true] - Invoke on the trailing
 *   edge of the timeout.
 * @returns {T} A new function with the same signature that is debounced.
 *
 * @example
 * ```typescript
 * const debouncedSearch = debounce(
 *   (query: string) => fetchResults(query),
 *   300
 * );
 * input.addEventListener("input", (e) => debouncedSearch(e.target.value));
 * ```
 */

Documenting the Callback Signature

For non-generic callbacks, use the @callback tag to define the expected signature:

/**
 * @callback FilterPredicate
 * @param {T} item - The current item being tested.
 * @param {number} index - The index of the current item.
 * @returns {boolean} True to keep the item, false to filter it out.
 */

/**
 * @param {FilterPredicate} predicate - The test function.
 */

Event Handler Callbacks

For DOM-style event handlers, document the event object type:

@param {(event: MouseEvent) => void} onClick - Called when the element is clicked.

Timing Documentation

Always document when the callback is invoked: synchronously during execution, asynchronously after completion, on each iteration, or only on certain conditions.