lib: improve hideStackFrames intellisense

[anonrig]

This is a draft pull request to improve the developer experience by fixing internal function's JSDoc declarations. I wanted to receive some feedback before investing time on this.

Previously, all functions that uses hideStackFrames was invalidly typed and was shown as a warning in IDEs (On WebStorm and Sublime).

I wanted to introduce T is boolean kind of type guards into the functions but could not find a solution for functions that does not return any boolean, but throws an error.

[aduh95]

Previously, all functions that uses hideStackFrames was invalidly typed and was shown as a warning in IDEs (On WebStorm and Sublime).

Why do you say it was invalid? What warning do you see?

[targos]

I wanted to introduce T is boolean kind of type guards into the functions but could not find a solution for functions that does not return any boolean, but throws an error.

In TypeScript, the return type for this kind of functions is asserts value is SomeType.

[anonrig]

Why do you say it was invalid? What warning do you see?

@aduh95 The previous error for all functions that use hideStackFrames was Invalid number of arguments

In TypeScript, the return type for this kind of functions is asserts value is SomeType.

@targos Most of our validate functions does not return a value, but throw's an error if assertion fails. In that scenario, T is SomeType type guard is not the correct approach. Do you know a way to assert the function input type without a return value?

[targos]

@anonrig Note the asserts keyword.

[anonrig]

Changing validateInteger jsdoc to the following improves the autocompletion.

/**
 * @function validateInteger
 * @param {never} value
 * @param {string} name
 * @param {number=} min
 * @param {number=} max
 * @returns {asserts value is number}
 */

[aduh95]

Can we not use the Closure Compiler syntax? We should be using JSDoc instead:

/**
 * @callback myCallback
 * @param {number} mandatory
 * @param {number} [optional]
 */

/** @type {myCallback} */
var cb;

[anonrig]

I did not really quite understand your point since JSDoc lacks certain functionality. JSDoc does not have @template syntax. How can we achieve the same thing with only JSDoc?

/**
 * @function validateOneOf
 * @template T
 * @param {T} value
 * @param {string} name
 * @param {T[]} oneOf
 */

[anonrig]

Thanks for the review @aduh95. I've fixed them all.

[aduh95]

LGTM, there's just one parameter that should be documented as optional

[aduh95]

Sorry for the back and forth, I still have some questions/suggestions

[aduh95]

Thanks, LGTM!

[aduh95]

Landed in ab9b590, thanks for the contribution 🎉