It looks like JSDoc supports overloading of functions with the @name fun @name fun^2
I think the following communicates your intent clearly
/**
@name example
@function
@param {string} required
@param {Function} callback
*/
/**
@name example^2
@function
@param {string} required
@param {string} [optional='DEFAULT VALUE']
@param {Function} callback
*/
function example() {
if(typeof optional === 'function' && typeof callback === 'undefined') {
callback = optional;
optional = 'DEFAULT VALUE';
}
// do work here
}
However, in your case, I think it would be easiest if you just switched your optional parameter to the end, then you won't need overloading
/**
* @param required
* @param {Function} callback
* @param {String} [optional='DEFAULT VALUE']
*/
function example(required, callback, optional) {
if (typeof optional === 'undefined') {
optional = 'DEFAULT VALUE';
}
// do work here
}