web-dev-qa-db-ja.com

JSDocのドキュメント非構造化関数パラメーター

以前は、オブジェクトパラメータを次のように常に文書化していました。

/**
 * 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
}

上記のアプローチでは、関数が2つの異なるパラメーターではなく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
}
argumentsecmascript-6jsdocdestructuring
46
morkro

documentation で説明されているように、これがその意図です。

/**
 * 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;
41
Cerbrus