Document destructured function parameter in JSDoc
ArgumentsEcmascript 6JsdocDestructuringArguments Problem Overview
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
}
Arguments Solutions
Solution 1 - Arguments
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.
*/
const 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
*/
const letters = ({a, b: {c}}) => a + c;
Solution 2 - Arguments
I personally use this one:
/**
* @param {{
a: number
b: number
}} param0
* @returns {number} The sum
*/
const func = ({ a, b }) => a + b;
Just create the object right there.
I also take advantage of TypeScript, and would declare obtional b
as b?
or b: number | undefined
as JSDoc also allows unions
Solution 3 - Arguments
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.
)