Раньше я всегда документировал параметры своего объекта следующим образом:
/**
* 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
}
config
в вашем коде или вообще есть какое-то имя.foo
иbar
. Это не окончательное решение, но любой подход с использованием объекта приводит к ошибкам проверки, а проверки и автозаполнения из IDE - это то, что меня больше всего волнует.Ответы:
Так оно и задумано, как описано в документации .
/** * 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;
источник
function ({a}, {a}) {}
. JSDoc, я думаю, будет@param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.a
, и полагаться на порядок@param
тегов?function ({a}, {a}) {}
неверный синтаксис, такa
как он определен дважды.({a: b}, {a}))
или({a}, {b})
- дело в том, что@param
теги JSDoc являются беспорядочными AFAIK, и ключи могут быть неоднозначными, если JSDoc пытается сопоставить с использованием имен свойств. Следующая версия VSCode будет использовать позиционный поиск для разрешения этого сценария.Я лично использую этот:
/** * @param {{ a: number b: number }} param0 * @returns {number} The sum */ const func = ({ a, b }) => a + b;
Просто создайте объект прямо здесь.
Я также воспользоваться машинопись , и объявит obtional в
b
качестве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, но оторванная от нее, также позволяет
@param {{x:number,y:number}} point A "point-shaped" object.
)источник
employee
в функции больше нет переменной.Project.prototype.assign = function({ name, department })
. Перед примером они говорят: «Если параметр деструктурируется без явного имени, вы можете присвоить объекту соответствующее имя и задокументировать его свойства».