Tukukkk

Previously I've always documented my object parameters as follows:

/**

 * Description of the function

 *

 * @param {Object} config - The configuration

 * @param {String} config.foo

 * @param {Boolean} [config.bar] - Optional value

 * @return {String}

 */

function doSomething (config = {}) {

  const { foo, bar } = config;

  console.log(foo, bar);

  // do something

}

But I am unsure what the best approach is with desctructured function parameter. Do I just ignore the object, define it somehow or what is the best way of documenting it?

/**

 * Description of the function

 *

 * @param {String} foo

 * @param {Boolean} [bar] - Optional value

 * @return {String}

 */

function doSomething ({ foo, bar } = {}) {

  console.log(foo, bar);

  // do something

}

I feel like my approach above doesn't make it obvious that the function expects an object and not two different parameter.

Another way I could think of would be using @typedef, but that might end up being a huge mess (especially in a larger file with many methods)?

/**

 * @typedef {Object} doSomethingConfiguration

 * @property {String} foo

 * @property {Boolean} [bar] - Optional value

 */



/**

 * Description of the function

 *

 * @param {doSomethingConfiguration}

 * @return {String}

 */

function doSomething ({ foo, bar } = {}) {

  console.log(foo, bar);

  // do something

}

This is how it's intended, as described in the documentation.

/**

 * My cool function.

 *

 * @param {Object} obj - An object.

 * @param {string} obj.prop1 - Property 1.

 * @param {string} obj.prop2 - Property 2.

 */

var fn = function ({prop1, prop2}) {

  // Do something with prop1 and prop2

}

So, your first example is pretty much correct.

Another example with some deeper nesting:

/**

 * Nesting example.

 *

 * @param {object} param

 * @param {number} param.a - First value

 * @param {object} param.b - Wrapper

 * @param {number} param.b.c - Second value

 * @return {number} sum a and b

 */

letters = ({a, b: {c}}) => a + c;

See JSDoc's "Documenting a parameter's properties":

/**

 * Assign the project to an employee.

 * @param {Object} employee - The employee who is responsible for the project.

 * @param {string} employee.name - The name of the employee.

 * @param {string} employee.department - The employee's department.

 */

Project.prototype.assign = function(employee) {

    // ...

};

(Google Closure compiler type checking, that was based on but diverted from JSDoc, also allows @param {{x:number,y:number}} point A "point-shaped" object.)