Как документировать список аргументов с переменной длиной с известными типами параметров?

по теме: правильный способ документирования функций аргументов открытого типа в 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: escape dollars в тексте замены, 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...

выше выглядит уродливо, но это должно дать вам представление о том, что я пытаюсь добиться:

  • документировать тип параметра переменной (в данном случае массива)
  • документировать значения этого массива
  • документировать свойства объекта внутри этого массива

для лени, я использовал массив вместо объекта. Другие предложения всегда приветствуются.

7
javascript jsdoc

2 ответов

ваша функция не является действительно переменными аргументами, вы должны просто изменить свою подпись на то, что предложила 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;
}
5

Если вы не ограничены каким-либо другим API, то первое, что я бы предложил, было бы:Не используйте массив ни для чего, кроме сбора данных, который вы собираетесь перебирать.

вероятно, лучшим подходом здесь было бы перефакторировать функцию так, чтобы она принимала три параметра или какой-то объект param. Например:

/**
 * @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 снаружи вашего контроля) , поскольку это окажется как хрупким, так и в конечном итоге немного запутанным.

2