web-dev-qa-db-ja.com

JSDocで無制限の引数関数をドキュメント化する正しい方法

次のようなものがあるとしましょう：

var someFunc = function() {
    // do something here with arguments
}

この関数がJSDocで任意の数の引数を取ることができることをどのように正しく文書化しますか？これは私の最良の推測ですが、それが正しいかどうかはわかりません。

/**
 * @param {Mixed} [...] Unlimited amount of optional parameters
 */
var someFunc = function() {
    // do something here with arguments
}

関連する： php-可変数のパラメーターをドッキングする方法

javascriptjsdoc
69
kflorence

JSDoc仕様 および GoogleのClosure Compiler は次のように実行します。

@param {...number} var_args

ここで、「number」は予想される引数のタイプです。

これの完全な使用法は、次のようになります。

/**
* @param {...*} var_args
*/
function lookMaImVariadic(var_args) {
    // Utilize the `arguments` object here, not `var_args`.
}

arguments（またはargumentsのオフセット）を使用して追加の引数にアクセスすることに関するコメントに注意してください。 var_args IDE引数が実際に存在することを知らせるために使用しただけです。

ES6の残りのパラメーター は、実際のパラメーターをさらに一歩進めて、提供された値を取り込めます（したがって、argumentsを使用する必要はありません）。

/**
* @param {...*} var_args
*/
function lookMaImES6Variadic(...var_args) {
    // Utilize the `var_args` array here, not `arguments`.
}
91
Dawson Toth

これを行う方法は、JSDocのドキュメントで 現在説明されている であり、Closureのドキュメントのように省略記号を使用しています。

_@param {...<type>} <argName> <Argument description>
_

省略記号の後に移動するには型を指定する必要がありますが、_*_を使用してすべての受け入れを記述するか、_|_を使用して複数の受け入れ可能な型を分離できます。生成されたドキュメントでは、JSDocはこの引数をrepeatableと記述します。同様に、オプション引数をoptional。

私のテストでは、実際のjavascript関数定義に引数を持つ必要はなかったので、実際のコードには空の括弧、つまりfunction whatever() { ... }だけを含めることができます。

シングルタイプ：

_@param {...number} terms Terms to multiply together
_

任意のタイプ（以下の例では、角括弧はitemsがオプションと反復可能の両方としてタグ付けされることを意味します）：

_@param {...*} [items] - zero or more items to log.
_

複数の型では、型リストの前後に括弧が必要です。省略記号は開始括弧の前にあります。

_@param {...(Person|string)} attendees - Meeting attendees, listed as either 
                                        String names or {@link Person} objects
_
22
Daniel Baird

私はかなり長い間これでびっくりしました。 Google Closure Compilerでこれを行う方法は次のとおりです。

/**
* @param {...*} var_args
*/
function my_function(var_args) {
    // code that accesses the magic 'arguments' variable...
}

重要なのは、関数にvar_argsパラメータ（または@paramステートメント）、関数が実際にそのパラメーターを使用しない場合でも。

10
Adrian Holovaty

JSDocユーザーグループ から：

公式な方法はありませんが、考えられる解決策の1つは次のとおりです。

/**
 * @param [...] Zero or more child nodes. If zero then ... otherwise ....
 */

角括弧はオプションのパラメーターを示し、...は（私にとって）「任意の数」を示します。

別の可能性はこれです...

/**
 * @param [arguments] The child nodes.
 */

どちらの方法でも、あなたの言っていることを伝える必要があります。

少し古いですが（2007年）、最新のものは知りません。

パラメータタイプを「混合」として文書化する必要がある場合は、{*}のように@param {*} [arguments]を使用します。

10
hashchange