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-可変数のパラメーターを文書化する方法

JSDocの仕様とGoogleの閉鎖コンパイラは、このようにそれを実行します。

@param {...number} var_args

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

したがって、これの完全な使用法は次のようになります。

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

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

ES6のRESTパラメーターは、実際のパラメーターをさらに一歩進めて、提供された値を含めることができます（したがって、これ以上使用するarguments必要はありません）。

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

これを行う方法は、JSDocドキュメントで説明されており、Closureドキュメントと同様に省略記号を使用しています。

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

省略記号の後に続くタイプを指定する必要がありますが、*を使用して何でも受け入れることを説明したり、|を使用して複数の受け入れ可能なタイプを区切ることができます。生成されたドキュメントでは、JSDocは、オプションの引数をオプションとして説明するのと同じように、この引数を繰り返し可能として説明します。

私のテストでは、実際の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

JSDocのユーザーグループ：

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

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

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

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

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

どちらの方法でも、あなたが何を意味するのかを伝える必要があります。

（2007）少し古いですが、私はそれ以上の最新のものを知りません。

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

私はかなり長い間これに夢中になりました。Google ClosureCompilerでそれを行う方法は次のとおりです。

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

重要なのは、関数が実際にそのパラメーターを使用していなくても、関数にvar_argsパラメーター（または@paramステートメントで呼び出すもの）を与えることです。