JDoc 中的文档解构函数参数

以前我总是记录我的对象参数如下:

/**
* 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
}
30657 次浏览
小开

见 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.)

小开

正如 文件中所描述的那样，这就是它的目的。

/**
* My cool function.
*
* @param {Object} obj - An object.
* @param {string} obj.prop1 - Property 1.
* @param {string} obj.prop2 - Property 2.
*/
const 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
*/
const letters = ({a, b: {c}}) => a + c;
小开

我个人用这个:

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

就在这里创建对象。

我还利用了 TypeScript ，并将非必需的 b声明为 b?或 b: number | undefined，声明为 < a href = “ https://JSDoc.app/tag-param.html # multi-type-and-repeat-properties”rel = “ noReferrer”> JSDoc 也允许联合


提交答案