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
}

但是我不确定使用分散的函数参数最好的方法是什么。我只是忽略对象，以某种方式定义它还是记录它的最佳方法是什么？

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

如文档中所述，这就是它的意图。

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

我个人使用这个：

/**
* @param {{
  a: number
  b: number
}} param0
* @returns {number} The sum
*/
const func = ({ a, b }) => a + b;

只需在此处创建对象。

我也借此打字稿的优势，并且宣称obtionalb作为b?或b: number | undefined作为JSDoc还允许工会

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

（Google Closure编译器类型检查（基于JSDoc但从JSDoc转移过来，也允许@param {{x:number,y:number}} point A "point-shaped" object.））