tools: enable jsdoc/require-property-description lint rule

[Trott]

No description provided.

[nodejs-github-bot]

Review requested:

• @nodejs/http
• @nodejs/modules
• @nodejs/net

[nodejs-github-bot]

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

[aduh95]

I'm not sure what's the point, if we were using those to generate .d.ts that could be used outside of core that would make sense, but as is it's just a duplication of the docs that is likely to get outdated at some point.

[Trott]

I'm not sure what's the point, if we were using those to generate .d.ts that could be used outside of core that would make sense, but as is it's just a duplication of the docs that is likely to get outdated at some point.

The JSDoc stuff was added for the benefit of people coding Node.js core using IDEs. For example, they can mouse over things and get a description of possible options values. Hopefully, one day, the JSDoc comments can be used to generate parts of the docs rather than have the information duplicated, but that will take a big effort by someone motivated. (Looking in @ovflowd's direction...)

[ovflowd]

The JSDoc stuff was added for the benefit of people coding Node.js core using IDEs. For example, they can mouse over things and get a description of possible options values. Hopefully, one day, the JSDoc comments can be used to generate parts of the docs rather than have the information duplicated, but that will take a big effort by someone motivated. (Looking in @ovflowd's direction...)

That is something that I haven't taken into consideration for the API docs as they were designed mostly for the publicly exposed APIs for Node.js,

I know some of the JSdoc would be faced to the public Node.js API's, but it actually never crossed my mind to extract them from the source during build docs build time.

It is something we could do, as in the new proposal, for module documentation, we define the sourceLinks which could also be very useful for "reading" the source file searching for extra docs for that method.

Not sure how complex it would be. I bet we could even use a JSDoc parser for reading those segments.

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/45370
✔  Done loading data for nodejs/node/pull/45370
----------------------------------- PR info ------------------------------------
Title      tools: enable jsdoc/require-property-description lint rule (#45370)
Author     Rich Trott  (@Trott)
Branch     Trott:jsdoc -> nodejs:main
Labels     http, tools, esm, author ready, needs-ci
Commits    4
 - http: add JSDoc property descriptions
 - esm: add JSDoc property descriptions for fetch
 - esm: add JSDoc property descriptions for loader
 - tools: enable jsdoc/require-property-description rule
Committers 1
 - Rich Trott 
PR-URL: https://github.com/nodejs/node/pull/45370
Reviewed-By: Akhil Marsonya 
Reviewed-By: Yagiz Nizipli 
Reviewed-By: Jacob Smith 
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/45370
Reviewed-By: Akhil Marsonya 
Reviewed-By: Yagiz Nizipli 
Reviewed-By: Jacob Smith 
--------------------------------------------------------------------------------
   ℹ  This PR was created on Tue, 08 Nov 2022 03:43:27 GMT
   ✔  Approvals: 3
   ✔  - Akhil Marsonya (@marsonya): https://github.com/nodejs/node/pull/45370#pullrequestreview-1171838195
   ✔  - Yagiz Nizipli (@anonrig): https://github.com/nodejs/node/pull/45370#pullrequestreview-1172185195
   ✔  - Jacob Smith (@JakobJingleheimer): https://github.com/nodejs/node/pull/45370#pullrequestreview-1176957120
   ✔  Last GitHub CI successful
   ℹ  Last Full PR CI on 2022-11-08T15:03:10Z: https://ci.nodejs.org/job/node-test-pull-request/47790/
- Querying data for job/node-test-pull-request/47790/
   ✔  Last Jenkins CI successful
--------------------------------------------------------------------------------
   ✔  No git cherry-pick in progress
   ✔  No git am in progress
   ✔  No git rebase in progress
--------------------------------------------------------------------------------
- Bringing origin/main up to date...
From https://github.com/nodejs/node
 * branch                  main       -> FETCH_HEAD
✔  origin/main is now up-to-date
- Downloading patch for 45370
From https://github.com/nodejs/node
 * branch                  refs/pull/45370/merge -> FETCH_HEAD
✔  Fetched commits as ca3ed363ffef..67637f1a3729
--------------------------------------------------------------------------------
[main 62b7ead5a8] http: add JSDoc property descriptions
 Author: Rich Trott 
 Date: Mon Nov 7 19:38:35 2022 -0800
 1 file changed, 22 insertions(+), 22 deletions(-)
[main 58d9257e8c] esm: add JSDoc property descriptions for fetch
 Author: Rich Trott 
 Date: Mon Nov 7 19:39:29 2022 -0800
 1 file changed, 3 insertions(+), 3 deletions(-)
[main a70c6745b8] esm: add JSDoc property descriptions for loader
 Author: Rich Trott 
 Date: Mon Nov 7 19:39:44 2022 -0800
 1 file changed, 7 insertions(+), 7 deletions(-)
[main f5591a2c58] tools: enable jsdoc/require-property-description rule
 Author: Rich Trott 
 Date: Mon Nov 7 19:41:12 2022 -0800
 1 file changed, 1 deletion(-)
   ✔  Patches applied
There are 4 commits in the PR. Attempting autorebase.
Rebasing (2/8)
Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

http: add JSDoc property descriptions
PR-URL: #45370

Reviewed-By: Akhil Marsonya akhil.marsonya27@gmail.com

Reviewed-By: Yagiz Nizipli yagiz@nizipli.com

Reviewed-By: Jacob Smith jacob@frende.me
[detached HEAD 44b064bc9c] http: add JSDoc property descriptions

Author: Rich Trott rtrott@gmail.com

Date: Mon Nov 7 19:38:35 2022 -0800

1 file changed, 22 insertions(+), 22 deletions(-)

Rebasing (3/8)

Rebasing (4/8)
Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

esm: add JSDoc property descriptions for fetch
PR-URL: #45370

Reviewed-By: Akhil Marsonya akhil.marsonya27@gmail.com

Reviewed-By: Yagiz Nizipli yagiz@nizipli.com

Reviewed-By: Jacob Smith jacob@frende.me
[detached HEAD eb181f9cd3] esm: add JSDoc property descriptions for fetch

Author: Rich Trott rtrott@gmail.com

Date: Mon Nov 7 19:39:29 2022 -0800

1 file changed, 3 insertions(+), 3 deletions(-)

Rebasing (5/8)

Rebasing (6/8)
Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

esm: add JSDoc property descriptions for loader
PR-URL: #45370

Reviewed-By: Akhil Marsonya akhil.marsonya27@gmail.com

Reviewed-By: Yagiz Nizipli yagiz@nizipli.com

Reviewed-By: Jacob Smith jacob@frende.me
[detached HEAD 881e997d26] esm: add JSDoc property descriptions for loader

Author: Rich Trott rtrott@gmail.com

Date: Mon Nov 7 19:39:44 2022 -0800

1 file changed, 7 insertions(+), 7 deletions(-)

Rebasing (7/8)

Rebasing (8/8)
Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

tools: enable jsdoc/require-property-description rule
PR-URL: #45370

Reviewed-By: Akhil Marsonya akhil.marsonya27@gmail.com

Reviewed-By: Yagiz Nizipli yagiz@nizipli.com

Reviewed-By: Jacob Smith jacob@frende.me
[detached HEAD a38c5ef6d9] tools: enable jsdoc/require-property-description rule

Author: Rich Trott rtrott@gmail.com

Date: Mon Nov 7 19:41:12 2022 -0800

1 file changed, 1 deletion(-)
Successfully rebased and updated refs/heads/main.
ℹ  Add commit-queue-squash label to land the PR as one commit, or commit-queue-rebase to land as separate commits.

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

[nodejs-github-bot]

Landed in ca3ed36...917987c