How to describe "object" arguments in jsdoc?

javascript

jsdoc

object-documentation

typescript

byAnton Shumikhin·Nov 1, 2024

Here's your fast-track solution for documenting an object parameter using JSDoc:

/**
 * Sets up a secure connection. Like a secret handshake!
 * @param {Object} options - The mysterious options object.
 * @param {string} options.url - The rendezvous point (i.e., the URL).
 * @param {number} [options.timeout=5000] - How long we wait until we call it quits (in ms, optionally).
 */
function initConnection(options) {
  // Spy-level code goes here...
}

@param enables you to provide a detailed property list, such as the compulsory url and the optional timeout with a default value of 5000 ms. Square brackets indicate optional parameters, and curly braces enclose their types.

Deep dive into object argument documentation

Ace your JSDoc object parameters with these techniques and turn your code documentation into an artifact of clarity and ease-of-use.

@typedef: Your tool for custom types

For complex objects, make life easier by defining a custom type once with @typedef. Use this type as a reference wherever needed. It's like calling in an old friend!

/**
 * @typedef {Object} ConnectionOptions
 * @property {string} url - Because getting lost is no fun!
 * @property {number} [timeout=5000] - Patience is a virtue, but you can only stretch it so much.
 */

/**
 * Begins a serious session of web sleuthing.
 * @param {ConnectionOptions} options - The rules of engagement for this espionage!
 */
function initialize(options) {
  // Your code is the decoder ring...
}

Indicating optional properties: Give 'em a choice!

When indicating optional properties, use square brackets or add |undefined next to the type. It's kind-of like asking, "Would you like fries with that?"

/**
 * @param {{ url: string, [timeout]: number | undefined }} options - Options on the menu.
 */

Documenting complex, nested properties

Marie Kondo your objects! For nested objects, neatly stack @param tags or birth a new @typedef to provide reference. Organization is the key to simplicity.

/**
 * @param {Object} specs - The device's secret dossier.
 * @param {string} specs.model - Model number or the device's secret name.
 * @param {{ width: number, height: number }} specs.dimensions - The geometry of the gadget.
 */

Get anonymous with record types

Use record types to describe an anonymous object with a known set of properties. No names needed!

/**
 * @param {Object.<string, number>} itemCounts - Object mapping item names to stockpile quantities. It's inventory day!
 */

Give life to abstract objects with examples

One of the best ways to explain something is to show it. Provide examples in your JSDoc to clearly demonstrate expected parameter formats and data types.

/**
 * Assigns chores to your product inventory.
 * @param {Object.<string, number>} inventory - Product names matched with their tasks.
 * Example:
 * {
 *   "apples": 50,
 *   "oranges": 20
 * }
 */

@return brings back treasures

When your function returns an object, use @return to guide fellow coders on the structure of the returned object. It's like an operator's manual for your function.

/**
 * Retrieves user's secrets... I mean, profile data.
 * @return {{name: string, age: number}} The user's (unclassified) profile information.
 */

Make your JSDoc comments more than just informative, make them a joy to read! It's about code, not War and Peace!

One `Object` to rule them all: Destructuring

Introduce destructuring and simplify property documentation. It's like naming the parts while you assemble the IKEA furniture.

/**
 * Kidnaps...err...processes user data.
 * @param {Object} user - The unsuspecting user object.
 * @param {string} user.name - The pseudonym.
 * @param {number} user.age - The sand grains in the hourglass.
 */
function processUserData({ name, age }) {
  // Code embark on a 'name' and 'age' treasure hunt...
}

Clearly signpost required and optional properties

Documenting required and optional keys in your object is crucial. Don't keep them guessing!

/**
 * Impersonates a transformer with widget configuration modifications.
 * @param {{requiredSize: string, optionalColor?: string}} config - The disguise codebook!
 */