7

関連：JSDocでオープンエンドの引数関数を文書化する正しい方法

arguments変数にアクセスして複数の配列を受け入れる関数があります。

/**
 * @param options An object containing options
 * @param [options.bind] blablabla (optional)
 */
function modify_function (options) {
    for (var i=1; i<arguments.length; i++) {
        // ...
    }
}

optionsこれで、他の各引数は、文書化する価値のある値を含む配列であることがわかりました。

[search_term, replacement, options]

（長い）説明を変数パラメーター行に入れることは考えていません。

@param {...}検索語、置換、およびそのオプションを含む配列。インデックス0：関数内の検索語。1：置換テキスト。2：オプションのオプション（catch_errors：エラーをキャッチしてログに記録する、escape：置換テキストのドルをエスケープする、pos：検索語の前に置換を配置する場合は "L"、後に配置する場合は "R"）読み取り可能なソリューションではなく、タイプは表示されません。

変数パラメーターのタイプと値を文書化する方法はありますか？

@param {...[]} An array with search terms, replacements and its options
@param {...[0]} The search term within the function
@param {...[1]} The replacement text 
@param {...[2]} An optional object with obtions for the replacement
@param {...[2].catch_errors} catches errors and log it
@param {...[2].escape} etc...

上記は醜いように見えますが、それは私が達成しようとしていることのアイデアをあなたに与えるはずです：

  • 変数パラメーター（この場合は配列）のタイプを文書化します
  • この配列の値を文書化します
  • この配列内のオブジェクトのプロパティを文書化する

怠惰のために、私はオブジェクトの代わりに配列を使用しました。他の提案はいつでも歓迎です。

4

2 に答える 2

5

あなたの関数は本当に可変の引数ではありません、あなたはただその署名をfoundramaが提案したものに変えるべきです。JSDocの構文がfoundramaの提案よりも少し優れていることを除いて

/**
 * @param {String} searchTerm
 * @param {String} replacementText
 * @param {Object} opts (optional) An object containing the replacement options
 * @param {Function} opts.catch_errors Description text
 * @param {Event} opts.catch_errors.e The name of the first parameter 
 *         passed to catch_errors
 * @param {Type} opts.escape Description of options
 */

そして、あなたはそれを次のように呼ぶでしょう

modify_text('search', 'replacement', {
    catch_errors: function(e) {

    },
    escape: 'someEscape'

});

varargsスタイルの場合が本当にある場合は、パラメーターリストの最後に渡すことができる同じタイプの変数である必要があります。これは、JSDoc標準ではありませんが、Googleが使用するものです。彼らのドキュメントで

/**
 * Sums its parameters
 * @param {...number} var_args Numbers to be added together
 * @return number
 */
function sum(/* num, num, ... */) { 
    var sum = 0;
    for (var i =0; i < arguments.length; i++) {
      sum += arguments[i];
    }
    return sum;
}
于 2012-05-07T19:53:18.087 に答える
2

他のAPIによって制限されていない限り、最初に提案するのは、反復する予定のデータコレクション以外には配列を使用しないことです。

おそらくここでの最善のアプローチは、3つのパラメーターまたはある種のパラメーターオブジェクトを受け取るように関数をリファクタリングすることです。例えば：

/**
 * @param {String} searchTerm
 * @param {String} replacementText
 * @param {Object} replacementOpts (optional) An object containing the replacement
 * options; optional values in the object include:<ul>
   <li>catch_errors {Type} description text...</li>
   <li>escape {Type} description text...</li></ul>
 */

配列を使用しないことを強くお勧めします（ここでも、「制御できないAPIに制限されている場合を除きます）。配列は脆弱であり、最終的には少し混乱する可能性があります。

于 2011-08-26T12:15:53.523 に答える