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

89

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

/**
 * 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
}
Моркро
источник
1
Я думаю, что первый подход все еще хорош. Никого не волнует, назван ли объект configв вашем коде или вообще есть какое-то имя.
Bergi
В WebStorm я обнаружил, что если я просто опишу параметры (после деструктурирования) и проигнорирую деструктурирование, это в основном работает, за исключением менее распространенных случаев. Итак, в вашем примере опишите два параметра fooи bar. Это не окончательное решение, но любой подход с использованием объекта приводит к ошибкам проверки, а проверки и автозаполнения из IDE - это то, что меня больше всего волнует.
Mörre

Ответы:

96

Так оно и задумано, как описано в документации .

/**
 * 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;
Cerbrus
источник
Я не понимаю, как JSDoc однозначно работает, когда у вас есть несколько деструктурированных аргументов, например function ({a}, {a}) {}. JSDoc, я думаю, будет @param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.a, и полагаться на порядок @paramтегов?
ZachB
@ZachB: function ({a}, {a}) {}неверный синтаксис, так aкак он определен дважды.
Cerbrus
1
Ой. ({a: b}, {a}))или ({a}, {b})- дело в том, что @paramтеги JSDoc являются беспорядочными AFAIK, и ключи могут быть неоднозначными, если JSDoc пытается сопоставить с использованием имен свойств. Следующая версия VSCode будет использовать позиционный поиск для разрешения этого сценария.
ZachB
1
Спасибо, @ d0gb3r7. Я обновил ссылку в ответе.
Cerbrus
-8

См . Документ 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.)

Якуб Голи
источник
2
Разве он уже не делает это? Он спрашивает, что делать теперь, когда employeeв функции больше нет переменной.
Bergi
7
Это не отвечает на вопрос - в этом примере деструктурирование не используется! С деструктуризацией у вас нет родительского объекта.
Mörre
На самом деле его та же ссылка, сразу после его примера, дает относительный пример с такими же точными комментариями jsdoc для Project.prototype.assign = function({ name, department }). Перед примером они говорят: «Если параметр деструктурируется без явного имени, вы можете присвоить объекту соответствующее имя и задокументировать его свойства».
notacouch