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.

Sign up for GitHub

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

Jump to bottom

lib: add JSDoc typings for util #38213

Closed
wants to merge 5 commits into from
Closed

lib: add JSDoc typings for util #38213

wants to merge 5 commits into from

Conversation

rohit-gohri
Copy link
Contributor

@rohit-gohri rohit-gohri commented Apr 12, 2021 •
edited
Loading

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.

bmeck
bmeck reviewed Apr 12, 2021
View reviewed changes
lib/util.js Outdated Show resolved Hide resolved
bmeck
bmeck reviewed Apr 12, 2021
View reviewed changes
lib/util.js Outdated Show resolved Hide resolved
bmeck
bmeck approved these changes Apr 12, 2021
View reviewed changes
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
mhdawson
mhdawson approved these changes Apr 16, 2021
View reviewed changes
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.

Sign in to view
@nodejs-github-bot
Copy link
Collaborator

CI: https://ci.nodejs.org/job/node-test-pull-request/37520/

@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
marsonya
marsonya requested changes Apr 19, 2021
View reviewed changes
Copy link
Member

@marsonya marsonya left a comment •
edited
Loading

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
marsonya
marsonya reviewed Apr 19, 2021
View reviewed changes
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

CI: https://ci.nodejs.org/job/node-test-pull-request/37648/

targos pushed a commit that referenced this pull request Apr 24, 2021
@rohit-gohri @targos
typings: add JSDoc typings for util
767d91b 
PR-URL: #38213
Refs: #38182
Refs: https://twitter.com/bradleymeck/status/1380643627211354115
Reviewed-By: Bradley Farias <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>
Reviewed-By: James M Snell <[email protected]>
@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
@rohit-gohri @targos
typings: add JSDoc typings for util
e389e86 
PR-URL: #38213
Refs: #38182
Refs: https://twitter.com/bradleymeck/status/1380643627211354115
Reviewed-By: Bradley Farias <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>
Reviewed-By: James M Snell <[email protected]>
@targos targos mentioned this pull request May 3, 2021
Merged
targos pushed a commit that referenced this pull request May 30, 2021
@rohit-gohri @targos
typings: add JSDoc typings for util
c116df7 
PR-URL: #38213
Refs: #38182
Refs: https://twitter.com/bradleymeck/status/1380643627211354115
Reviewed-By: Bradley Farias <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>
Reviewed-By: James M Snell <[email protected]>
targos pushed a commit that referenced this pull request Jun 5, 2021
@rohit-gohri @targos
typings: add JSDoc typings for util
69a60c0 
PR-URL: #38213
Refs: #38182
Refs: https://twitter.com/bradleymeck/status/1380643627211354115
Reviewed-By: Bradley Farias <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>
Reviewed-By: James M Snell <[email protected]>
@targos targos mentioned this pull request Jun 6, 2021
Merged
targos pushed a commit that referenced this pull request Jun 11, 2021
@rohit-gohri @targos
typings: add JSDoc typings for util
e35a354 
PR-URL: #38213
Refs: #38182
Refs: https://twitter.com/bradleymeck/status/1380643627211354115
Reviewed-By: Bradley Farias <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>
Reviewed-By: James M Snell <[email protected]>
@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
Reviewers

@marsonya marsonya marsonya requested changes

@bmeck bmeck bmeck approved these changes

@mhdawson mhdawson mhdawson approved these changes

@jasnell jasnell jasnell approved these changes

Assignees
No one assigned
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
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
7 participants
@rohit-gohri @bmeck @mhdawson @nodejs-github-bot @targos @jasnell @marsonya