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: add JSDoc typings for util #38213

Closed
wants to merge 5 commits into from

Conversation

rohit-gohri
Copy link
Contributor

@rohit-gohri rohit-gohri commented Apr 12, 2021

Ref: #38182
Ref: https://twitter.com/bradleymeck/status/1380643627211354115

Added JSDoc typings to lib/util. Most of the typings are pretty simple and direct, all the isThing methods have been typed using type predicates.

callbackify is a bit complex, for this I used the new Leading Rest elements in tuple types to infer types.

Before:

image

After:

image

There are still some errors with checkJs enabled that I'm not sure how to fix since we are mutating the original type:

image

@nodejs-github-bot nodejs-github-bot added needs-ci PRs that need a full CI run. util Issues and PRs related to the built-in util module. labels Apr 12, 2021
@bmeck
Copy link
Member

bmeck commented Apr 12, 2021

No need to fix all the checkJs errors for now! it is going to be an iterative process that will get easier as more types are added throughout core.

lib/util.js Outdated Show resolved Hide resolved
lib/util.js Outdated Show resolved Hide resolved
Copy link
Member

@bmeck bmeck left a comment

Choose a reason for hiding this comment

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

nits but LGTM

rohit-gohri and others added 2 commits April 12, 2021 23:15
Co-authored-by: Bradley Farias <bradley.meck@gmail.com>
Co-authored-by: Bradley Farias <bradley.meck@gmail.com>
Copy link
Member

@mhdawson mhdawson left a comment

Choose a reason for hiding this comment

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

LGTM

@mhdawson

This comment has been minimized.

@nodejs-github-bot
Copy link
Collaborator

@mhdawson mhdawson added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Apr 16, 2021
Copy link
Member

@marsonya marsonya left a comment

Choose a reason for hiding this comment

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

Many of the util functions are deprecated.
Should we use jsdoc's @deprecated tag to mark them as such?

lib/util.js Show resolved Hide resolved
lib/util.js Show resolved Hide resolved
lib/util.js Show resolved Hide resolved
lib/util.js Show resolved Hide resolved
lib/util.js Show resolved Hide resolved
lib/util.js Show resolved Hide resolved
lib/util.js Show resolved Hide resolved
lib/util.js Show resolved Hide resolved
lib/util.js Show resolved Hide resolved
lib/util.js Show resolved Hide resolved
lib/util.js Show resolved Hide resolved
@rohit-gohri
Copy link
Contributor Author

Many of the util functions are deprecated.
Should we use jsdoc's @deprecated tag to mark them as such?

Added @deprecated tags since Typescript does support them (https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-0.html#-deprecated--support)

@targos
Copy link
Member

targos commented Apr 20, 2021

Many of the util functions are deprecated.
Should we use jsdoc's @deprecated tag to mark them as such?

Added @deprecated tags since Typescript does support them (https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-0.html#-deprecated--support)

It is supported by TypeScript but the goal of JSDoc in core files is not to duplicate the public-facing documentation. Maybe it's fine in this case, because we don't use these functions in core, but we have to be careful about this (avoid too much duplication, focus on typings and other small changes that help core developers).

@targos targos self-assigned this Apr 24, 2021
@nodejs-github-bot
Copy link
Collaborator

targos pushed a commit that referenced this pull request Apr 24, 2021
PR-URL: #38213
Refs: #38182
Refs: https://twitter.com/bradleymeck/status/1380643627211354115
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
@targos
Copy link
Member

targos commented Apr 24, 2021

Landed in 767d91b

@targos targos closed this Apr 24, 2021
@rohit-gohri rohit-gohri deleted the jsdoc-util branch April 24, 2021 12:56
targos pushed a commit that referenced this pull request Apr 29, 2021
PR-URL: #38213
Refs: #38182
Refs: https://twitter.com/bradleymeck/status/1380643627211354115
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
@targos targos mentioned this pull request May 3, 2021
targos pushed a commit that referenced this pull request May 30, 2021
PR-URL: #38213
Refs: #38182
Refs: https://twitter.com/bradleymeck/status/1380643627211354115
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
targos pushed a commit that referenced this pull request Jun 5, 2021
PR-URL: #38213
Refs: #38182
Refs: https://twitter.com/bradleymeck/status/1380643627211354115
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
targos pushed a commit that referenced this pull request Jun 11, 2021
PR-URL: #38213
Refs: #38182
Refs: https://twitter.com/bradleymeck/status/1380643627211354115
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
@targos targos removed their assignment Oct 31, 2021
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. needs-ci PRs that need a full CI run. util Issues and PRs related to the built-in util module.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants