Параметр функції деструктурованої документа в 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у вашому коді, чи він взагалі не має імені.
Бергі

У WebStorm я виявив, що якщо я просто описую параметри (після деструктуризації) та ігнорую деструктуризацію, це здебільшого працює, за винятком менш поширених випадків. Отже, у вашому прикладі опишіть два параметри fooта bar. Це не остаточне рішення, але будь-який підхід із використанням об’єкта призводить до помилок перевірки - а перевірки та автозавершення з IDE - це те, що мене найбільше турбує.
Мерре

Відповіді:


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;

Я не бачу, як JSDoc однозначно працює, коли у вас є кілька деструктурованих аргументів, наприклад function ({a}, {a}) {}. JSDoc, мабуть, буде @param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.a, і покладається на упорядкування @paramтегів?
ZachB

@ZachB: function ({a}, {a}) {}недійсний синтаксис, оскільки aтам визначений двічі.
Цербрус,

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у функції більше немає змінної.
Бергі

7
Це не відповідає на питання - цей приклад не використовує деструктурування! З деструктуризацією у вас немає батьківського об'єкта.
Мерре

Насправді його те саме посилання, відразу після його прикладу, дає відносний приклад з однаковими коментарями jsdoc для Project.prototype.assign = function({ name, department }). До прикладу вони кажуть: "Якщо параметр деструктурований без явного імені, ви можете дати об'єкту відповідне і задокументувати його властивості".
notacouch
Використовуючи наш веб-сайт, ви визнаєте, що прочитали та зрозуміли наші Політику щодо файлів cookie та Політику конфіденційності.
Licensed under cc by-sa 3.0 with attribution required.