How do I document functions that have multiple parameter order options in JsDoc?

Question

I have a function for removing event handlers from an EventEmitter class. It looks something like this:

EventEmitter.prototype.remove_handler = function(event_name, handler) {
    if(arguments.length < 2) {
        handler = event_name;
        event_name = null;
    }

    // ...
};

The function can either be called with an event name and a handler, or just the handler. If the event name is present, the handler is removed from that specific event, otherwise it's completely removed from the event emitter.

How do I document such scenarios in JsDoc? In this case I could certainly just document the parameters as they appear and note that "event_name can be omitted, in whice case (etc...)", but I can certainly imagine scenarios where that would be impossible.

Answer 1

You can use the @also tag to provide multiple method signatures:

/**
 *
 * @param {String} event_name
 * @param {Function} handler
 *
 * @also
 *
 * @param {Function} handler
 */
EventEmitter.prototype.remove_handler = function(event_name, handler) {