JSDoc for Destructured Parameters

Documenting Destructured Parameters

Destructured parameters are common in modern JavaScript and TypeScript. The JSDoc approach uses dot notation to document each property of the destructured object.

Example Signature

function createUser({
  name,
  email,
  role = "viewer",
  preferences: { theme = "dark", language = "en" },
}: CreateUserInput): User

Generated JSDoc

/**
 * Creates a new user account with the specified profile and preferences.
 *
 * @param {CreateUserInput} options - The user creation options.
 * @param {string} options.name - The user's display name (1-100 characters).
 * @param {string} options.email - The user's email address. Must be unique.
 * @param {string} [options.role="viewer"] - The user's role. Defaults to "viewer".
 * @param {object} options.preferences - User preference settings.
 * @param {string} [options.preferences.theme="dark"] - The UI theme.
 *   Defaults to "dark".
 * @param {string} [options.preferences.language="en"] - The preferred
 *   language code. Defaults to "en".
 * @returns {User} The created user object with a generated ID.
 * @throws {ValidationError} If the email is invalid or already in use.
 */

Dot Notation Rules

JSDoc uses dot notation to document nested properties:

Pattern	Meaning
@param options	The top-level parameter
@param options.name	A property of options
@param options.prefs.theme	A nested property
@param [options.role]	An optional property
@param [options.role="viewer"]	Optional with default

TSDoc Alternative

In TSDoc, you can use a @param for the entire object and link to the interface type:

/**
 * @param options - See {@link CreateUserInput} for property details.
 */

Array Destructuring

For array destructuring ([first, ...rest]), name the parameter and document it as an array:

/**
 * @param {[string, ...string[]]} items - First item is the primary,
 *   rest are alternates.
 */