lib,test,tools: use consistent JSDoc types

[Trott]

This could be in preparation of implementing the jsdoc/check-types
ESLint rule.

[Trott]

This is the result of installing and enabling check-types from eslint-plugin-jsdoc. I'd check that into core but unfortunately it adds over 100K lines of code, so...uh...maybe not.

[Trott]

This is the result of installing and enabling check-types from eslint-plugin-jsdoc. I'd check that into core but unfortunately it adds over 100K lines of code, so...uh...maybe not.

(If it's possible to install and use only check-types and not the entire eslint-plugin-jsdoc, that would be fewer lines of code, of course. I haven't looked into that.)

[VoltrexKeyva]

I think we should change all of the objects in the JSDoc typings to Record (Indicating an object) and provide types as Record<TYPE, TYPE> (Indicating an object with types, e.g. Record<string, number> -> properties as strings (e.g. test: or 'test':, both works with that type) and the property values as numbers), as the object type in JSDoc typings is always shown as the any type, which does not imply an actual object.

[Mesteery]

I think we should change all of the objects in the JSDoc typings to Record (Indicating an empty object)

Record without type arguments is invalid.

[VoltrexKeyva]

I think we should change all of the objects in the JSDoc typings to Record (Indicating an empty object)

Record without type arguments is invalid.

Yep, didn't mean to explain it that way; updated the comment.

[aduh95]

In our docs we are using Object rather than object everywhere. Are we planing to update that to keep the consistency?

[Trott]

In our docs we are using Object rather than object everywhere. Are we planing to update that to keep the consistency?

I think this requires a larger discussion. If we're going to use JSDoc, let's use JSDoc and use it to generate information in our docs. If we've just got some JSDoc comments here and there but they aren't actually serving a purpose, let's remove them. Otherwise, we have to keep information in two places, but only for some APIs, and there's probably no obvious reason for which APIs that would be.

[aduh95]

but they aren't actually serving a purpose

I disagree, they are useful for core developers to get useful autocomplete features from their code editor. That being said I agree it would be better to use it to generate the docs, but I don’t think we should remove it if we can’t.

[Trott]

I disagree, they are useful for core developers to get useful autocomplete features from their code editor.

Ah, OK, if that's the primary purpose at the current time, then sure, let's keep them. I'm not concerned about using Object in docs and object in JSDoc, but I understand if others are. I usually like consistency, so I get. I just feel like internal consistency (all docs use the same thing, all JSDoc comments use the same thing) is more important.

[Trott]

I'd check that into core but unfortunately it adds over 100K lines of code, so...uh...maybe not.

If #40995 lands, then adding eslint-plugin-jsdoc will add "only" 93K lines, although over 20K of those lines would be the eslint-plugin-jsdoc README file.

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/40989
✔  Done loading data for nodejs/node/pull/40989
----------------------------------- PR info ------------------------------------
Title      lib,test,tools: use consistent JSDoc types (#40989)
Author     Rich Trott  (@Trott)
Branch     Trott:jsdoc-fix -> nodejs:master
Labels     lib / src, author ready, needs-ci
Commits    1
 - lib,test,tools: use consistent JSDoc types
Committers 1
 - Rich Trott 
PR-URL: https://github.com/nodejs/node/pull/40989
Reviewed-By: Michaël Zasso 
Reviewed-By: Luigi Pinca 
Reviewed-By: Antoine du Hamel 
Reviewed-By: Tobias Nießen 
Reviewed-By: Mohammed Keyvanzadeh 
Reviewed-By: Ruben Bridgewater 
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/40989
Reviewed-By: Michaël Zasso 
Reviewed-By: Luigi Pinca 
Reviewed-By: Antoine du Hamel 
Reviewed-By: Tobias Nießen 
Reviewed-By: Mohammed Keyvanzadeh 
Reviewed-By: Ruben Bridgewater 
--------------------------------------------------------------------------------
   ℹ  This PR was created on Sat, 27 Nov 2021 00:19:42 GMT
   ✔  Approvals: 6
   ✔  - Michaël Zasso (@targos) (TSC): https://github.com/nodejs/node/pull/40989#pullrequestreview-817141936
   ✔  - Luigi Pinca (@lpinca): https://github.com/nodejs/node/pull/40989#pullrequestreview-817156177
   ✔  - Antoine du Hamel (@aduh95) (TSC): https://github.com/nodejs/node/pull/40989#pullrequestreview-817158923
   ✔  - Tobias Nießen (@tniessen) (TSC): https://github.com/nodejs/node/pull/40989#pullrequestreview-817168406
   ✔  - Mohammed Keyvanzadeh (@VoltrexMaster): https://github.com/nodejs/node/pull/40989#pullrequestreview-817189140
   ✔  - Ruben Bridgewater (@BridgeAR) (TSC): https://github.com/nodejs/node/pull/40989#pullrequestreview-817207135
   ✔  Last GitHub Actions successful
   ✖  No Jenkins CI runs detected
--------------------------------------------------------------------------------
   ✔  Aborted `git node land` session in /home/runner/work/node/node/.ncu

https://github.com/nodejs/node/actions/runs/1514030857

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[nodejs-github-bot]

Landed in 1e8b296