multiple API variants

[David Luzar]

How would you go about defining multiple API variants that are so dissimilar to each other that defining them inside one JSDoc @param's list would be very confusing? Does docdown support this?

E.g., take this method:

Possible API variants:
1: #on( {string}, {string}, {Function} );
2: #on( {string}, {Function} );
3: #on( {Object}, {string} );

Putting it inside one JSDOC would result in something like this:

@param {string|Object} [a] if string, optional... if Object, not optional.
@param {string|Function} b if 1st arg object, this should be... Else this should be ...
@param {Function} [c] if previous 2args supplied, this should be handler...

Which we'd be better off not using @param at all, and simply writing it out in an @example or notes.

Thoughts?

[John-David Dalton]

I jam them into the @param but if you're that overloaded it might be a sign that you may need to split your method into multiple specialized methods.