multiple API variants
dwelle opened this issue · comments
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?
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.