doc: make error descriptions more concise#16954

Trott · 2017-11-11T15:44:46Z

Remove the practice of starting most error descriptions with "Used when"
or wordier variations.

Change errors of the form:

Used when the type of an asynchronous resource is invalid.

...to:

The type of an asynchronous resource was invalid.

Change errors of the form:

The 'ERR_INVALID_CURSOR_POS' is thrown specifically when a cursor on
a given stream is attempted to move to a specified row without a specified
column.

...to:

A cursor on a given stream cannot be moved to a specified row without
a specified column.

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

errors doc

maclover7

left a few comments, some are just adding a comma here or there, feel free to treat as nits :)

maclover7 · 2017-11-11T22:54:13Z

doc/api/errors.md

could --> could not?

Done. I also removed properly as it seems superfluous.

maclover7 · 2017-11-11T22:55:03Z

doc/api/errors.md

comma after disable FIPS mode?

done, thanks

maclover7 · 2017-11-11T22:57:31Z

doc/api/errors.md

I know it wasn't there originally, but should HTTP be changes to HTTP/2?

It would seem so. Done.

maclover7 · 2017-11-11T22:58:41Z

doc/api/errors.md

comma after by the client?

done, thanks

jasnell

LGTM. FWIW, once the error conversion is complete, I'm planning a sprint of changes to fill in the details on these errors in the docs, including example code (where possible) showing how to trigger the error and an explanation on how to fix it.

benjamingr

Making @maclover7 's nit explicit - otherwise looks like a nice positive change

Trott · 2017-11-12T14:03:48Z

@benjamingr I've addressed all of @maclover7's nits and also edited a few more messages that landed since I originally opened this. PTAL. (I left these changes in separate commits for easier reviewing if you don't want to read everything all over again.)

maclover7 · 2017-11-12T14:10:18Z

LGTM

benjamingr · 2017-11-12T15:00:16Z

@Trott just in case you haven't noticed I've approved those changes (after your commit but before your comment).

Trott · 2017-11-14T19:22:07Z

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

joyeecheung

Left a bunch of suggestions...for better consistency 😅

joyeecheung · 2017-11-15T11:36:05Z

doc/api/errors.md

There is an extra e in receivee

joyeecheung · 2017-11-15T11:36:28Z

doc/api/errors.md

s/Streams/streams?

joyeecheung · 2017-11-15T11:36:43Z

doc/api/errors.md

s/Streams/streams?

joyeecheung · 2017-11-15T11:39:02Z

doc/api/errors.md

s/contains/contained/?

joyeecheung · 2017-11-15T11:40:40Z

doc/api/errors.md

The previous descriptions are using an attempt was made to..., we may want to be consistent here.

joyeecheung · 2017-11-15T12:20:16Z

doc/api/errors.md

Extra space at the end.

joyeecheung · 2017-11-15T12:20:45Z

doc/api/errors.md

For consistency, An attempt was made to enable...but FIPS mode was not available.

joyeecheung · 2017-11-15T12:21:23Z

doc/api/errors.md

s/is/was/

joyeecheung · 2017-11-15T12:21:39Z

doc/api/errors.md

Maybe drop the when?

I think I'll go with if instead.

joyeecheung · 2017-11-15T12:22:23Z

doc/api/errors.md

s/is/was/

Remove the practice of starting most error descriptions with "Used when" or wordier variations. Change errors of the form: > Used when the type of an asynchronous resource is invalid. ...to: > The type of an asynchronous resource was invalid. Change errors of the form: > The `'ERR_INVALID_CURSOR_POS'` is thrown specifically when a cursor on > a given stream is attempted to move to a specified row without a specified > column. ...to: > A cursor on a given stream cannot be moved to a specified row without > a specified column.

Trott · 2017-11-15T23:28:14Z

Addressed almost all of the awesome nits from @joyeecheung. PTAL

joyeecheung

Thanks for bearing with me :D

Trott · 2017-11-17T00:28:23Z

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

Remove the practice of starting most error descriptions with "Used when" or wordier variations. Change errors of the form: > Used when the type of an asynchronous resource is invalid. ...to: > The type of an asynchronous resource was invalid. Change errors of the form: > The `'ERR_INVALID_CURSOR_POS'` is thrown specifically when a cursor on > a given stream is attempted to move to a specified row without a > specified column. ...to: > A cursor on a given stream cannot be moved to a specified row without > a specified column. PR-URL: nodejs#16954 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>

Trott · 2017-11-17T17:58:14Z

Landed in 959c425.

MylesBorins · 2017-12-11T22:10:28Z

Should this be backported to v9.x-staging? If yes please follow the guide and raise a backport PR, if not let me know or add the dont-land-on label.

Remove the practice of starting most error descriptions with "Used when" or wordier variations. Change errors of the form: > Used when the type of an asynchronous resource is invalid. ...to: > The type of an asynchronous resource was invalid. Change errors of the form: > The `'ERR_INVALID_CURSOR_POS'` is thrown specifically when a cursor on > a given stream is attempted to move to a specified row without a > specified column. ...to: > A cursor on a given stream cannot be moved to a specified row without > a specified column. PR-URL: nodejs#16954 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>

Trott · 2017-12-11T23:33:35Z

@MylesBorins Backport is in #17622

Remove the practice of starting most error descriptions with "Used when" or wordier variations. Change errors of the form: > Used when the type of an asynchronous resource is invalid. ...to: > The type of an asynchronous resource was invalid. Change errors of the form: > The `'ERR_INVALID_CURSOR_POS'` is thrown specifically when a cursor on > a given stream is attempted to move to a specified row without a > specified column. ...to: > A cursor on a given stream cannot be moved to a specified row without > a specified column. Backport-PR-URL: #17622 PR-URL: #16954 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>

gibfahn · 2017-12-19T22:44:53Z

@Trott backports for v6.x and v8.x? Feel free to mark don't land if it's a hassle.

Trott · 2017-12-19T23:04:19Z

@Trott backports for v6.x and v8.x? Feel free to mark don't land if it's a hassle.

Node.js error codes don't exist in 6.x so marking as dont-land for that version.

They exist in 8.x so I'll take a closer look at that...

Remove the practice of starting most error descriptions with "Used when" or wordier variations. Change errors of the form: > Used when the type of an asynchronous resource is invalid. ...to: > The type of an asynchronous resource was invalid. Change errors of the form: > The `'ERR_INVALID_CURSOR_POS'` is thrown specifically when a cursor on > a given stream is attempted to move to a specified row without a > specified column. ...to: > A cursor on a given stream cannot be moved to a specified row without > a specified column. PR-URL: nodejs#16954 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>

Trott · 2017-12-19T23:14:38Z

@gibfahn 8.x backport in #17767 and assigned to you.

Remove the practice of starting most error descriptions with "Used when" or wordier variations. Change errors of the form: > Used when the type of an asynchronous resource is invalid. ...to: > The type of an asynchronous resource was invalid. Change errors of the form: > The `'ERR_INVALID_CURSOR_POS'` is thrown specifically when a cursor on > a given stream is attempted to move to a specified row without a > specified column. ...to: > A cursor on a given stream cannot be moved to a specified row without > a specified column. PR-URL: #16954 Backport-PR-URL: #17767 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Joyee Cheung <[email protected]>

Trott added doc Issues and PRs related to the documentations. errors Issues and PRs related to JavaScript errors originated in Node.js core. labels Nov 11, 2017

nodejs-github-bot added doc Issues and PRs related to the documentations. errors Issues and PRs related to JavaScript errors originated in Node.js core. labels Nov 11, 2017

maclover7 reviewed Nov 11, 2017
View reviewed changes

jasnell approved these changes Nov 12, 2017
View reviewed changes

gireeshpunathil approved these changes Nov 12, 2017
View reviewed changes

benjamingr requested changes Nov 12, 2017
View reviewed changes

Trott force-pushed the used-when branch from 6e1bab8 to 37b6913Compare November 12, 2017 14:00

benjamingr approved these changes Nov 12, 2017
View reviewed changes

Trott mentioned this pull request Nov 14, 2017
crypto: Better docs for cases where peer's public key is invalid #16849
Closed
4 tasks

tniessen approved these changes Nov 15, 2017
View reviewed changes

joyeecheung reviewed Nov 15, 2017
View reviewed changes

Trott added 6 commits November 15, 2017 14:38

squash: fix errors that have landed since this opened
b9e372c

squash: cpuUsage nit from maclover7
2edcd00

squash: comma nits from maclover7
5fadfe0

squash: HTTP/2 nit from maclover7
b9fd330

squash: mega-nits from joyee
f85b90d

Trott force-pushed the used-when branch from cb2ece2 to f85b90dCompare November 15, 2017 23:28

joyeecheung approved these changes Nov 16, 2017
View reviewed changes

Trott closed this Nov 17, 2017

MylesBorins added the backport-requested-v9.x label Dec 11, 2017

Trott mentioned this pull request Dec 11, 2017
[v9.x backport] doc: make error descriptions more concise #17622
Closed
4 tasks

Trott removed the backport-requested-v9.x label Dec 11, 2017

MylesBorins added the backported-to-v9.x label Dec 12, 2017

MylesBorins mentioned this pull request Dec 12, 2017
v9.3.0 proposal #17631
Merged

gibfahn added backport-requested-v6.x labels Dec 19, 2017

Trott added dont-land-on-v6.x and removed backport-requested-v6.x labels Dec 19, 2017

Trott mentioned this pull request Dec 19, 2017
[v8.x backport] doc: make error descriptions more concise #17767
Closed
3 tasks

gibfahn added backported-to-v8.x and removed backport-requested-v8.x labels Dec 20, 2017

gibfahn mentioned this pull request Dec 20, 2017
v8.9.4 proposal #17772
Closed

gibfahn mentioned this pull request Dec 20, 2017
v8.9.4 proposal #17774
Merged

Trott deleted the used-when branch January 13, 2022 22:47

Uh oh!

doc: make error descriptions more concise#16954

doc: make error descriptions more concise #16954

Uh oh!

Conversation

Trott commented Nov 11, 2017

Checklist

Affected core subsystem(s)

Uh oh!

maclover7 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jasnell left a comment

Choose a reason for hiding this comment

Uh oh!

benjamingr left a comment

Choose a reason for hiding this comment

Uh oh!

Trott commented Nov 12, 2017

Uh oh!

maclover7 commented Nov 12, 2017

Uh oh!

benjamingr commented Nov 12, 2017

Uh oh!

Trott commented Nov 14, 2017

Uh oh!

joyeecheung left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Trott commented Nov 15, 2017

Uh oh!

joyeecheung left a comment

Choose a reason for hiding this comment

Uh oh!

Trott commented Nov 17, 2017

Uh oh!

Trott commented Nov 17, 2017

Uh oh!

MylesBorins commented Dec 11, 2017

Uh oh!

Trott commented Dec 11, 2017

Uh oh!