JSDocで非構造化関数パラメーターを文書化する


90

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

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

しかし、desctructured関数パラメーターを使用するのが最善のアプローチであるかどうかはわかりません。オブジェクトを無視するか、何らかの方法で定義するか、それとも文書化するための最良の方法は何ですか?

/**
 * Description of the function
 *
 * @param {String} foo
 * @param {Boolean} [bar] - Optional value
 * @return {String}
 */
function doSomething ({ foo, bar } = {}) {
  console.log(foo, bar);
  // do something
}

上記の私のアプローチでは、関数がobject2つの異なるパラメーターではなく1つのパラメーターを期待していることが明確になっていないように感じます。

私が考えることができる別の方法はを使用すること@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コードで名前が付けられているか、名前がまったくないかは誰も気にしません。
ベルギ2016年

WebStormで、(破棄後の)パラメーターを記述し、破棄を無視すると、あまり一般的でない場合を除いて、ほとんど機能することがわかりました。したがって、あなたの例では、2つのパラメータ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;

のように複数の非構造化引数がある場合、JSDocがどのように明確に機能するかわかりませんfunction ({a}, {a}) {}。私が推測するJSDoc@param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.aは、@paramタグの順序に依存しますか?
zachB 2018

@ZachB:function ({a}, {a}) {}a2回定義されているため、無効な構文です。
Cerbrus 2018

1
おっと。({a: b}, {a}))または({a}, {b})-ポイントは、JSDoc@paramタグは順序のないAFAIKであり、JSDocがプロパティ名を使用して照合しようとすると、キーがあいまいになる可能性があるということでした。VSCodeの次のバージョンでは、位置ルックアップを使用してこのシナリオを解決します。
zachB 2018

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) {
    // ...
};

(JSDocに基づいているが、JSDocから転用された、Google Closureコンパイラの型チェックも可能です@param {{x:number,y:number}} point A "point-shaped" object.


2
彼はすでにそれをしていませんか?employee関数に変数がなくなったので、彼は今何をすべきかを尋ねています。
ベルギ2016年

7
これは質問に答えません-この例は破壊を使用していません!破棄すると、親オブジェクトがなくなります。
Mörre

実際、彼の例の直後の彼の同じリンクは、とまったく同じjsdocコメントを含む相対的な例を示していProject.prototype.assign = function({ name, department })ます。例の前に、「パラメータが明示的な名前なしで非構造化されている場合、オブジェクトに適切な名前を付けて、そのプロパティを文書化できます」と彼らは言います。
notacouch
弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.