Как вы документируете JSDoc со смешанным типом параметра?

Как документировать метод в Javascript, используя JSDoc, когда тип параметра может быть смешан?

У меня есть метод в объекте Dialog, где я могу показать HTML или мои собственные Viewable объекты. Метод JSDoc выглядит следующим образом:

/**
 * Can pass in viewable object, or some HTML element
 *
 * @param viewable viewable {Viewable} or HTML element {HTMLElement} or String {string}
 * @param {Boolean} cancelable is cancellable
 * @param title string or data object of String and Id {Title:String, Id:String} for setting HTML id value
 * @param {Array} actions array of functions actions display buttons on the bottom connecting to the passed in functions
 * @param {String} size mode. Can be mini,small,medium,large,maxi. Or of type {width:number, height:number}
 * @param {Number} zindex starting z-order. Note: first level dialog = 10,11,12, second level dialog 13,14,15 etc.
 */
Dialog.showElement = function(viewable, cancelable, title, actions, mode, zindex){
..
}

Поскольку JS не разрешает перегрузку метода, мне нужно создать эти типы методов, где paramater в методе может быть двумя разрозненными типами. Есть ли способ документировать это в JSDoc или может JSDoc разрешить вам документировать параметр с одним типом?

Также как бы вы документируете параметр типа {Title: String, Id: String}? То есть объект, переданный в этом, не относится к типу. Квази, объект JSON.

Ответ 1

Вы можете использовать разделитель |, чтобы указать несколько типов в сигнатуре типа метода:

/**
 * Some method
 * @param {Object|string|number} param The parameter.
 * @returns {Object|string|number} The modified param.
 */
function doSomething(param) {
    return etc..
};

Ответ 2

Документы Google Closure Compiler рекомендуют следующую форму - которая выглядит официальной, так как она найдена на usejsdoc.org:

/**
 * Some method
 * @param {(Object|string|number)} param The parameter.
 * @returns {(Object|undefined)} The modified param.
 */
function doSomething(param) {
    return etc..
};

Чтобы привести приведенные выше ссылки на компилятор замыкания:

Обратите внимание на скобки, которые требуются.