Параметр деструктурированной функции документа в JSDoc

Ранее я всегда документировал параметры моего объекта следующим образом:

/**
 * 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
}

Но я не уверен, что лучший подход с параметром функции desctructured. Я просто игнорирую объект, определяю его как-то или как лучше всего документировать его?

/**
 * Description of the function
 *
 * @param {String} foo
 * @param {Boolean} [bar] - Optional value
 * @return {String}
 */
function doSomething ({ foo, bar } = {}) {
  console.log(foo, bar);
  // do something
}

Мне кажется, что мой подход выше не делает очевидным, что функция ожидает object, а не два разных параметра.

Другим способом, который я мог бы подумать, будет использовать @typedef, но это может стать огромным беспорядком (особенно в большем файле со многими методами)?

/**
 * @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
}

Ответ 1

Так оно и было, насколько я могу найти на jsdoc3 repo:

/**
 * 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
}

Итак, ваш первый пример в значительной степени верен.

Другой пример с более глубоким вложением:

/**
 * 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;

Ответ 2

См. JSDoc "Документирование свойств параметров" :

/**
 * 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 department.
 */
Project.prototype.assign = function(employee) {
    // ...
};

(Проверка типа компилятора Google Closure, которая была основана, но переадресована из JSDoc, также позволяет @param {{x:number,y:number}} point A "point-shaped" object.)