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

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

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

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

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


javascript jsdoc
person Lekensteyn    schedule 25.06.2011    source источник
comment
Я думаю, что индексированный 0, 1, ... k - не лучший способ. Вместо этого используйте буквы или последовательности букв.   -  person sergzach    schedule 27.07.2011
comment
@sergzach: массив индексируется цифрами, а не буквами. Я думаю, что ответ в том, что я должен быть менее ленивым.   -  person Lekensteyn    schedule 27.07.2011

Ответы (2)


arrow_upward
5
arrow_downward

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

arrow_upward
2
arrow_downward

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

person founddrama    schedule 26.08.2011