Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

lib: improve hideStackFrames intellisense #44181

Merged
merged 11 commits into from
Aug 17, 2022
Merged

Conversation

anonrig
Copy link
Member

@anonrig anonrig commented Aug 8, 2022

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.

@nodejs-github-bot nodejs-github-bot added errors Issues and PRs related to JavaScript errors originated in Node.js core. needs-ci PRs that need a full CI run. labels Aug 8, 2022
@anonrig anonrig marked this pull request as ready for review August 8, 2022 20:43
@aduh95
Copy link
Contributor

aduh95 commented Aug 16, 2022

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
Copy link
Member

targos commented Aug 16, 2022

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
Copy link
Member Author

anonrig commented Aug 16, 2022

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

Screen Shot 2022-08-16 at 8 19 44 AM

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
Copy link
Member

targos commented Aug 16, 2022

@anonrig Note the asserts keyword.

@anonrig
Copy link
Member Author

anonrig commented Aug 16, 2022

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

Screen Shot 2022-08-16 at 8 39 20 AM

@aduh95
Copy link
Contributor

aduh95 commented Aug 16, 2022

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
Copy link
Member Author

anonrig commented Aug 16, 2022

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
 */

lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Show resolved Hide resolved
lib/internal/validators.js Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Show resolved Hide resolved
lib/internal/validators.js Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
@anonrig
Copy link
Member Author

anonrig commented Aug 17, 2022

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

Copy link
Contributor

@aduh95 aduh95 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
Copy link
Contributor

@aduh95 aduh95 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Outdated Show resolved Hide resolved
Copy link
Contributor

@aduh95 aduh95 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, LGTM!

@aduh95 aduh95 added author ready PRs that have at least one approval, no pending requests for changes, and a CI started. and removed needs-ci PRs that need a full CI run. labels Aug 17, 2022
lib/internal/validators.js Outdated Show resolved Hide resolved
lib/internal/validators.js Show resolved Hide resolved
lib/internal/validators.js Show resolved Hide resolved
lib/internal/validators.js Show resolved Hide resolved
@aduh95 aduh95 added the typings label Aug 17, 2022
@aduh95 aduh95 merged commit ab9b590 into nodejs:main Aug 17, 2022
@aduh95
Copy link
Contributor

aduh95 commented Aug 17, 2022

Landed in ab9b590, thanks for the contribution 🎉

ruyadorno pushed a commit that referenced this pull request Aug 23, 2022
PR-URL: #44181
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Fyko pushed a commit to Fyko/node that referenced this pull request Sep 15, 2022
PR-URL: nodejs#44181
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
juanarbol pushed a commit that referenced this pull request Oct 3, 2022
PR-URL: #44181
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
@juanarbol juanarbol mentioned this pull request Oct 4, 2022
juanarbol pushed a commit that referenced this pull request Oct 4, 2022
PR-URL: #44181
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
juanarbol pushed a commit that referenced this pull request Oct 7, 2022
PR-URL: #44181
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
juanarbol pushed a commit that referenced this pull request Oct 10, 2022
PR-URL: #44181
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
juanarbol pushed a commit that referenced this pull request Oct 11, 2022
PR-URL: #44181
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
guangwong pushed a commit to noslate-project/node that referenced this pull request Jan 3, 2023
PR-URL: nodejs/node#44181
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
guangwong pushed a commit to noslate-project/node that referenced this pull request Jan 3, 2023
PR-URL: nodejs/node#44181
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
author ready PRs that have at least one approval, no pending requests for changes, and a CI started. errors Issues and PRs related to JavaScript errors originated in Node.js core. typings
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants