Skip to content

lib: add JSDoc typings for util#38213

Closed
rohit-gohri wants to merge 5 commits intonodejs:masterfrom
rohit-gohri:jsdoc-util
Closed

lib: add JSDoc typings for util#38213
rohit-gohri wants to merge 5 commits intonodejs:masterfrom
rohit-gohri:jsdoc-util

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
bmeck
bmeck reviewed Apr 12, 2021
View reviewed changes
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
@rohit-gohri @bmeck
lib: added undefined and sorted return type
b16a9b1 
Co-authored-by: Bradley Farias <bradley.meck@gmail.com>
@rohit-gohri @bmeck
lib: update return type
d9dfb9d 
Co-authored-by: Bradley Farias <bradley.meck@gmail.com>
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

nodejs-github-bot commented Apr 16, 2021

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?

marsonya
marsonya reviewed Apr 19, 2021
View reviewed changes
rohit-gohri
rohit-gohri commented Apr 20, 2021
View reviewed changes
@rohit-gohri
Copy link
Contributor Author

rohit-gohri 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)

@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

nodejs-github-bot commented Apr 24, 2021

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 <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
@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 <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
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 <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
@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 <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 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 <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

Reviewers

@marsonya marsonya marsonya requested changes

@jasnell jasnell jasnell approved these changes

@mhdawson mhdawson mhdawson approved these changes

+1 more reviewer

@bmeck bmeck bmeck approved these changes

Reviewers whose approvals may not affect merge requirements

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