How do you document JSDoc with mixed parameter type?

Question

How do I document a method in JavaScript using JSDoc when the parameter type can be mixed?

I have method on a Dialog object where I can show HTML or my own Viewable objects. The method JSDoc looks like this:

/**  * 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){ .. } 

Because JS doesn't allow method overloading, I need to create these types of methods, where a parameter in a method can be two disparate types. Is there a way to document this in JSDoc, or can JSDoc only let you document a param with one type?

Also how would you document a paramater of type {Title:String, Id:String}? That is, an object passed in that is not of a type. Quasi, a JSON object.

Answer 1

You can use the | separator to specify multiple types in the method type signature:

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