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} */varcb;

[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 🎉