Sergey Panfilov Sergey Panfilov - 1 month ago 9
Javascript Question

How to documet inconsistent returns with JsDoc

Is it possible to add

@return
jsdoc annotation for function with inconsistent returns?

/**
* @param {Number} a
* @param {Number} b
* @return {Number}
* */
function sum (a, b) {
if (a < b) return false; //here we have a Boolean
return a + b; //and here a Number
}


Attention:


  1. I already know that this is bad;

  2. I won't do it in my code;

  3. Just interesting how everyone handle this issue (in other ways than refactoring);


Answer

There's an example right there in the JSDoc @returns documentation:

The return value can have different types

/**
 * Returns the sum of a and b
 * @param {Number} a
 * @param {Number} b
 * @param {Boolean} retArr If set to true, the function will return an array
 * @returns {Number|Array} Sum of a and b or an array that contains a, b and the sum of a and b.
 */
function sum(a, b, retArr) {
    if (retArr) {
        return [a, b, a + b];
    }
    return a + b;
}

E.g., use |, as you do other times the type may vary.