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.

Just explain it in plain text in the general comment section for the function, and declare the parameter that is optional as such. — Mörre
– Mörre, Commented Feb 9, 2013 at 8:09
@Mörre: Yes, as I said in my question, that works in this case, but what about a function with a more drastic variety of parameter options? For example, a function that accepts two completely different sets of arguments. You'd need to document it almost as if it was two functions, and you'd need at least two @param lines for each parameter. That is the sort of situation I'm curious about. — Hubro
– Hubro, Commented Feb 9, 2013 at 11:13
As I said, explain it in the comment section in plain text, and leave out @param if that complicates things. Or really HAVE two functions. I'm not so sure what I'd say to functions that have completely different argument options... I'll defer judgment until I see a concrete case and then I'll only judge that case. — Mörre
– Mörre, Commented Feb 9, 2013 at 21:24

Louis · Accepted Answer · 2014-04-04 00:25:40Z

5

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) {

answered Apr 4, 2014 at 0:25

Louis

152k28 gold badges287 silver badges332 bronze badges

Sign up to request clarification or add additional context in comments.

Collectives™ on Stack Overflow

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

1 Answer 1

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related