JSDoc for Functions with Default Parameters

Documenting Default Parameters

When a function parameter has a default value, the JSDoc comment should indicate both that the parameter is optional and what the default value is. This helps consumers of the API know which arguments they can omit.

Example Signature

function formatDate(
  date: Date,
  locale: string = "en-US",
  options: Intl.DateTimeFormatOptions = { dateStyle: "medium" }
): string

Generated JSDoc

/**
 * Formats a Date object into a localized string representation.
 *
 * @param {Date} date - The date to format.
 * @param {string} [locale="en-US"] - The BCP 47 locale tag. Defaults to "en-US".
 * @param {Intl.DateTimeFormatOptions} [options] - Formatting options.
 *   Defaults to { dateStyle: "medium" }.
 * @returns {string} The formatted date string.
 */

JSDoc Syntax for Defaults

In JSDoc, optional parameters with defaults use square brackets around the name:

• @param {string} [locale="en-US"] — optional with default
• @param {string} [locale] — optional without specifying default
• @param {string} locale — required

When Types Are Inferred

If you use TypeScript and TSDoc style, the type is already in the signature, so you don't need braces. But you should still mention the default value in the description text:

/**
 * @param locale - The BCP 47 locale tag. Defaults to "en-US".
 */

Documenting Complex Defaults

For object defaults, describe the shape in the parameter description rather than trying to encode the entire default object in the tag syntax.