документы середины функция необязательных параметры

Question

Существуют ли правильный синтаксис для документирования дополнительных параметров JavaScript, где необязательный параметр приходит в середине заголовка функции (думает, Jquery, глоток и т.д.)

Я документировал функционирует стандартным способом и работает отлично. Уловка, когда я пытаюсь установить второй параметр в последнюю переменную (в случае, когда необязательный параметр не использовался), моя IDE запутывается.

Пример:

/** 
* @param {number} a_num 
* @param {string} [a_str=''] 
* @param {{}} a_obj 
*/ 
function (a_num, a_str, a_obj) { 
    if (!a_obj) a_obj = a_str; // doesn't want me to save a string to an object. 
    a_str = ''; 
    // more stuff 
} 

Если это имеет значение, я использую PhpStorm от JetBrains, который использует стиль Закрытие Google КОХ (в основном). Хотя я ищу более общий подход, основанный на передовой практике.

Я подозреваю, что я мог бы сделать что-то уродливое, как:

/** 
* @param {number} a_num 
* @param {string|{}} a_str 
* @param {{}} [a_obj=null] 
*/ 

Но что на самом деле не описать ситуацию настолько точно, как хотелось бы. Я надеюсь, так как это становится общей структурой, что есть что-то, чтобы справиться с этим должным образом.

Answer 1

Аннотирование дополнительных параметров в середине списка параметров функции почти так же сложно, как и поддерживающий код, который использует этот тип сигнатуры метода.

1. Javascript по-настоящему не поддерживает необязательные параметры в середине списка аргументов функции (для этого вам нужны именованные параметры). Вместо этого функции, которые рекламируют это, пытаются определить, какая версия функции была вызвана на основе количества и значений параметров.

2. Javascript также не поддерживает перегрузку функции.

Признание этих ограничений дает первые подсказки для поддержки того, что по существу является стратегией документации. Ваша аннотация должна поддерживать все типы вызовов - и при этом вы теряете определенную степень безопасности при использовании инструмента, который применяет или проверяет типы.

Давайте использовать один из jQuery.prototype.bind подписей в качестве примера:

jQuery.prototype.bind(eventType [, eventData ], handler) 

Документально этот метод, мы понимаем, что два параметра всегда. Сначала давайте переставить и переименовать параметры:

jQuery.prototype.bind(eventType, eventDataOrHandler, [ handler ]) 

С этой перегруппировкой JSDoc становится яснее:

/** 
* @param {string} eventType 
* @param {(*|function(Event))} eventDataOrHandler 
* @param {function(Event)=} handler 
* @return {!jQuery} 
*/ 
jQuery.prototype.bind = 
    function(eventType, eventDataOrHandler, handler) {}; 

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

Прослушивание Closure-compiler jQuery externs даст вам массу примеров.