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.

This might not be part of the original JSDoc specification (I don't know), but have a look at this article which explains how to annotate JS for the Google Closure compiler: https://developers.google.com/closure/compiler/docs/js-for-compiler#types. It also has an example for "record types". — Felix Kling, May 27 '13 at 10:40

score 72 · Accepted Answer · answered May 27 '13 at 10:37

72

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..
};

answered May 27 '13 at 10:37

flavian

28,161
11
65
105

but what about my {Title:String, Id:String} thing. Can I only document that as {Object} ? – Oliver Watkins May 27 '13 at 11:09
1

so if I had that, and a string, would I document it like @param {String|{title: String, id: Object}} param ? – Oliver Watkins May 27 '13 at 11:25
1

@OliverWatkins For objects, you can do the following `@param {object|string} obj` `@param {string} obj.a` `@param {string} obj.b` – Ruan Mendes Mar 13 '14 at 00:57
@flavian Do you have references for your example? The official docs i could ever find so far require parentheses for this (see my answer below) - thus i believe this answer is formally wrong... – Philzen Jan 26 '15 at 03:00

score 11 · Answer 2 · answered Jan 26 '15 at 02:57

Google Closure Compiler Docs recommend the following form - which looks official as it is the same as found on usejsdoc.org:

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

To cite the above linked closure compiler docs:

Note the parentheses, which are required.

How do you document JSDoc with mixed parameter type?

2 Answers2

Linked