error: document removed error codes by SirR4T · Pull Request #22100 · nodejs/node

SirR4T · 2018-08-03T04:22:27Z

Checklist

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

Working towards #22061

List of errors to be documented as removed (from #21491)

vsemozhetbyt

Some initial nits.

vsemozhetbyt · 2018-08-03T22:29:28Z

Linter issue: 80 characters per line limit exceeded.

vsemozhetbyt · 2018-08-03T22:29:50Z

Linter issue: 80 characters per line limit exceeded.

vsemozhetbyt · 2018-08-03T22:31:44Z

Linter issue: missing heading for this link?
Doc tools use underscores, not hyphens in auto-created section ids, with document name prefix: #errors_legacy_node_js_error_codes for ## Legacy Node.js Error Codes.

doh! missed adding the h2 header, fixing it now. Also, realized that I don't really need the link definition at the end of the file, so removed it.

vsemozhetbyt · 2018-08-06T06:29:09Z

I may be wrong, but we may need not this hardcoded id, as the other ones in this doc may be due to legacy links support. Let us see what others think.

BridgeAR · 2018-08-06T06:54:43Z

It would be nice if we add a "removed: v10.x.x". I guess that might not be parsed properly tough. @vsemozhetbyt do you have a suggestion for this?

We may add the case for removing to adding and deprecating. It seems these two function need to be updated accordingly:
node/tools/doc/common.js
Line 14 in 2bea9ce
functionextractAndParseYAML(text){
node/tools/doc/html.js
Line 258 in 2bea9ce
functionparseYAML(text){
(Just grepping 'added' or 'deprecated' and adding a similar case may do)

@BridgeAR added these sections (thanks @vsemozhetbyt, for the pointers), now shows up as
Although cc: @joyeecheung , because it seems to me she has some reservations against saying "removed in v10.x.x" .

Also, should there be a short explanation on why this error code was removed? Something on the lines of
Like fs.watchFile(), this situation is now silently ignored.
or some such.

@SirR4T I think it's OK to have removed in, but the version number should be accurate. In the case of ERR_FS_WTCHER_ALREADY_STARTED, it has never been released in any version, since the commit that added it (6c25f2e) and the commit that removed it (301f6cc) are both present from v10.0.0...v10.8.0 - which means when v10.0.0 was out, the error was not even there. Therefore, this error code has only appeared in nightly and canary releases.

If we do add a short explanation, we can make this in changes blocks.

got it. If the error codes never actually touched the releases, what should the description look like? is having both added: v10.0.0 and removed: v10.0.0 ok?

@joyeecheung : also, I have added versions added and versions removed here, for all the commits which either added or removed the error codes. Eyeballing the versions, it seems to me that the wherever github mentions vA.a.a .. vB.b.b, we should be mentioning the vB.b.b in the docs. (For both added, as well as removed.) will that be correct?

I think annotating them as added: v10.0.0 removed: v10.0.0 is more confusing than helpful. A note in the docs about that would be enough, maybe something like:
This error code has never been released and only existed in nightly builds.

vsemozhetbyt · 2018-08-07T16:35:43Z

Intermediate CI-lite: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/451/

SirR4T · 2018-08-08T09:30:27Z

if someone can confirm this looks good, I'll continue adding the other error codes.

vsemozhetbyt

Doc format and doctools additions LGTM.

SirR4T · 2018-08-22T10:46:15Z

additional info, could be useful.

Error Name	Removed in Commit : Versions	Added in Commit : Versions
`ERR_FS_WATCHER_ALREADY_STARTED`	`301f6cc` : v10.9.0 .. v10.0.0	`6c25f2e` : v10.9.0 .. v10.0.0
`ERR_FS_WATCHER_NOT_STARTED`	`301f6cc` : v10.9.0 .. v10.0.0	`6c25f2e` : v10.9.0 .. v10.0.0
`ERR_HTTP2_ALREADY_SHUTDOWN`	`6e1c25c` : v10.9.0 .. v10.0.0	`0babd18` : v10.9.0 .. v10.0.0
`ERR_HTTP2_ERROR`	`1cdb41f` : v10.9.0 .. v9.0.0	`e71e71b` : v10.9.0 .. v9.0.0
`ERR_HTTP2_FRAME_ERROR`	`6e1c25c` : v10.9.0 .. v10.0.0	`e71e71b` : v10.9.0 .. v9.0.0
`ERR_HTTP2_HEADERS_OBJECT`	`6e1c25c` : v10.9.0 .. v10.0.0	`e71e71b` : v10.9.0 .. v9.0.0
`ERR_HTTP2_HEADER_REQUIRED`	`6e1c25c` : v10.9.0 .. v10.0.0	`1cdb41f` : v10.9.0 .. v9.0.0
`ERR_HTTP2_INFO_HEADERS_AFTER_RESPOND`	`6e1c25c` : v10.9.0 .. v10.0.0	`e71e71b` : v10.9.0 .. v9.0.0
`ERR_HTTP2_STREAM_CLOSED`	`0babd18` : v10.9.0 .. v10.0.0	`e71e71b` : v10.9.0 .. v9.0.0
`ERR_HTTP_INVALID_CHAR`	`6e1c25c` : v10.9.0 .. v10.0.0	`1cdb41f` : v10.9.0 .. v9.0.0
`ERR_INVALID_ARRAY_LENGTH`	`186857f` :	`8ca9338` : v10.9.0 .. v9.0.0
`ERR_INVALID_DOMAIN_NAME`	`564048d` :	`bdfbce9` : v10.9.0 .. v9.0.0
`ERR_INVALID_REPL_HISTORY`	`e6b69b9` : v10.9.0 .. v9.0.0	`8ca9338` : v10.9.0 .. v9.0.0
`ERR_MISSING_DYNAMIC_INSTANTIATE_HOOK`	`6e1c25c` : v10.9.0 .. v10.0.0	`14181a3` : v10.9.0 .. v10.0.0
`ERR_NAPI_CONS_PROTOTYPE_OBJECT`	`6e1c25c` : v10.9.0 .. v10.0.0	`1cdb41f` : v10.9.0 .. v9.0.0
`ERR_OUTOFMEMORY`	`a82b1b7` : v10.9.0 .. v10.0.0	`1cdb41f` : v10.9.0 .. v9.0.0
`ERR_PARSE_HISTORY_DATA`	`6e1c25c` : v10.9.0 .. v10.0.0	`8ca9338` : v10.9.0 .. v9.0.0
`ERR_STREAM_HAS_STRINGDECODER`	`1b54371` : v10.9.0 .. v9.0.0	`8ca9338` : v10.9.0 .. v9.0.0
`ERR_STREAM_READ_NOT_IMPLEMENTED`	`c979488` : v10.9.0 .. v10.0.0	`88fb359` : v10.9.0 .. v9.0.0
`ERR_STRING_TOO_LARGE`	`3626944` : v10.9.0 .. v10.0.0	`289d152` : v10.9.0 .. v10.0.0
`ERR_TLS_RENEGOTIATION_FAILED`	`6e1c25c` : v10.9.0 .. v10.0.0	`1cdb41f` : v10.9.0 .. v9.0.0
`ERR_UNKNOWN_BUILTIN_MODULE`	`1cdb41f` : v10.9.0 .. v9.0.0	`251e5ed` : v10.9.0 .. v8.0.0
`ERR_VALUE_OUT_OF_RANGE`	`d022cb1` : v10.9.0 .. v10.0.0	`4d893e0` : v10.9.0 .. v9.0.0
`ERR_ZLIB_BINDING_CLOSED`	`5e3f516` : v10.9.0 .. v10.0.0	`7489141` : v10.9.0 .. v9.0.0

vsemozhetbyt · 2018-08-23T15:07:31Z

+removed: v10.0.0
+-->
+
+HTTP/2 Informational headers must only be sent *prior* to calling the


Nit: Informational -> informational (lower case).

vsemozhetbyt · 2018-08-23T15:12:29Z

+removed: REPLACEME
+-->
+
+Used when `hostname` can not be parsed from a provided URL.


can not -> cannot

vsemozhetbyt · 2018-08-23T15:17:19Z

+removed: v10.0.0
+-->
+
+The `repl` module was unable parse data from the REPL history file.


unable parse -> unable to parse

vsemozhetbyt · 2018-08-23T15:18:26Z

+
+Used to prevent an abort if a string decoder was set on the Socket.
+
+Example


Maybe omit the word Example as obvious.

vsemozhetbyt · 2018-08-23T15:21:21Z

+const Socket = require('net').Socket;
+const instance = new Socket();
+
+instance.setEncoding('utf-8');


'utf-8' -> 'utf8'

joyeecheung · 2018-08-23T20:19:56Z

Thanks for digging into this! On how to document the added and removed fields, in general:

If the commit that added the code and the commit that removed code appear in the same set of tags, then the code has never actually been released. In this case I think adding a note like This error code has never been released and only existed in nightly builds. would be enough.
If the commit that removed the code has not appear in any tags, that means it has not been actually removed in releases. We should leave them out in this PR and document them in another PR with the dont-land or semver-major labels similar to the PR that removes it.
If the commit that added the code and the commit that removed code appear in different set of tags, then the smalles tag where the adding commit appears is what added field should be, and the smallest tag where the removing commit appears is what the removed field should be

Documentation can be added once the PRs land on a release. Do not add documentation for those error codes yet. [See point 2 here](nodejs#22100 (comment)).

SirR4T · 2018-08-24T04:15:10Z

@vsemozhetbyt : regarding 1., I believe current YAML for doc sections only supports added, removed, and changes. Any idea on how to add the This error code has never been released and only existed in nightly builds. comment to all the relevant codes? Do we support footnotes / references like wikipedia does? Seems a waste to me, to add the same line duplicated in every relevant section.

regarding 2., have removed docs for the two error codes (ERR_INVALID_ARRAY_LENGTH and ERR_INVALID_DOMAIN_NAME) in this PR, and raised #22496 for the same.

regarding 3., yay! I was on track.

vsemozhetbyt · 2018-08-24T05:29:07Z

@SirR4T As changes: section items also require version keys, I cannot think of any ready appropriate place for this. @nodejs/documentation, are there any common places for these notes or should we introduce a new way to express them?

joyeecheung · 2018-08-24T14:31:13Z

@SirR4T

I believe current YAML for doc sections only supports added, removed, and changes. Any idea on how to add the This error code has never been released and only existed in nightly builds. comment to all the relevant codes? Do we support footnotes / references like wikipedia does? Seems a waste to me, to add the same line duplicated in every relevant section.

I think we can just skip those? If they are not even released there is no point adding those fields. A note in the docs would be enough.

SirR4T · 2018-08-25T08:22:59Z

@joyeecheung @vsemozhetbyt Have moved these errors to another list, as I wasn't sure how to add a note. Lemme know if this looks good..

vsemozhetbyt · 2018-08-25T08:31:29Z

 Used when an attempt is made to use a `zlib` object after it has already been
 closed.

+<a id="unreleased_error_codes">


It seems this anchor is unneeded (as well as the <a id="legacy-nodejs-error-codes"></a> above). We use hardcoded anchors only for error headings in this doc.

done. Also, any other suggestions welcome, for the last section description. The current These errors have never been released, but had been present on master between releases. seems to assume knowledge of the git repo on the behalf of a reader.

vsemozhetbyt · 2018-08-25T08:32:50Z

It seems like a good solution for me.

joyeecheung · 2018-08-26T03:08:33Z

 }

+ if (meta.removed) {
+ meta.removed = arrify(meta.removed);


Is this needed for this PR? From what I can tell we only used single removed fields here?

I was blindly copy pasting wherever added occurred.
Maybe not for this particular PR, but if we're planning to add removed as a feature for api docs, would rather it supports semver-minors as well, like added and deprecated.

@SirR4T Ah, sorry, I thought we already had removed before, looks like it is new in this PR...

joyeecheung

Great work, thanks for picking this up!

One note: this should be landed as two commits, one for the doc change and one for the tools change

joyeecheung · 2018-08-26T03:52:01Z

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/676/

PR-URL: #22100 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

PR-URL: #22100Fixes: #22061 Refs: #21491 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

vsemozhetbyt · 2018-08-26T07:52:12Z

Landed in e10290c...e9876fd
Thank you!

PR-URL: #22100 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

PR-URL: #22100Fixes: #22061 Refs: #21491 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

PR-URL: #22100 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

PR-URL: #22100Fixes: #22061 Refs: #21491 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

PR-URL: #22100 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

PR-URL: #22100Fixes: #22061 Refs: #21491 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

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 Aug 3, 2018

SirR4T mentioned this pull request Aug 3, 2018
errors: documenting removed error codes #22061
Closed
2 tasks

vsemozhetbyt reviewed Aug 3, 2018
View reviewed changes

SirR4T force-pushed the updateErrorDocs-22061 branch from 1444f20 to cbe275cCompare August 6, 2018 05:50

vsemozhetbyt reviewed Aug 6, 2018
View reviewed changes

BridgeAR reviewed Aug 6, 2018
View reviewed changes

SirR4T force-pushed the updateErrorDocs-22061 branch 2 times, most recently from 218bc9e to 0c11e4dCompare August 7, 2018 04:45

vsemozhetbyt approved these changes Aug 8, 2018
View reviewed changes

Sarat Addepalliand others added 5 commits August 23, 2018 10:43

[WIP] error: documenting removed error codes.
0546c6a

doc: fix linter issues for legacy error codes
25a533f

doc: Fix linter issues in errors.md
208cb4f

doc: add YAML parsers for removed sections
9b53c58

doc: update list of deprecated / removed error codes
dd31ede

SirR4T force-pushed the updateErrorDocs-22061 branch from dcc5a1b to dd31edeCompare August 23, 2018 05:15

SirR4T changed the title ~~[WIP] error: document removed error codes~~error: document removed error codesAug 23, 2018

vsemozhetbyt reviewed Aug 23, 2018
View reviewed changes

SirR4T added 2 commits August 24, 2018 09:29

docs: fix typos in error docs
1ad00f2

doc: errors that have been removed but not released
e77d298
Documentation can be added once the PRs land on a release. Do not add documentation for those error codes yet. [See point 2 here](nodejs#22100 (comment)).

SirR4T mentioned this pull request Aug 24, 2018
Update error docs for removed error codes, where code hasn't been released yet. #22496
Closed

error: reorder errors which were never released
e536153

vsemozhetbyt reviewed Aug 25, 2018
View reviewed changes

doc: removed hard coded handles where unnecessary
f10d321

joyeecheung reviewed Aug 26, 2018
View reviewed changes

joyeecheung approved these changes Aug 26, 2018
View reviewed changes

vsemozhetbyt pushed a commit that referenced this pull request Aug 26, 2018
doc: support 'removed' field in doc YAML sections
c917540
PR-URL: #22100 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

vsemozhetbyt pushed a commit that referenced this pull request Aug 26, 2018
doc: document removed error codes
e9876fd
PR-URL: #22100Fixes: #22061 Refs: #21491 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

vsemozhetbyt closed this Aug 26, 2018

SirR4T deleted the updateErrorDocs-22061 branch August 26, 2018 08:29

addaleax pushed a commit that referenced this pull request Aug 27, 2018
doc: support 'removed' field in doc YAML sections
b5ae3f8
PR-URL: #22100 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

addaleax pushed a commit that referenced this pull request Aug 27, 2018
doc: document removed error codes
35d6b4c
PR-URL: #22100Fixes: #22061 Refs: #21491 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

targos pushed a commit that referenced this pull request Sep 3, 2018
doc: support 'removed' field in doc YAML sections
c833d83
PR-URL: #22100 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

targos pushed a commit that referenced this pull request Sep 3, 2018
doc: document removed error codes
2875f72
PR-URL: #22100Fixes: #22061 Refs: #21491 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

targos mentioned this pull request Sep 5, 2018
Release proposal: v10.10.0 #22716
Merged

targos pushed a commit that referenced this pull request Sep 6, 2018
doc: support 'removed' field in doc YAML sections
060a62f
PR-URL: #22100 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

targos pushed a commit that referenced this pull request Sep 6, 2018
doc: document removed error codes
10b7404
PR-URL: #22100Fixes: #22061 Refs: #21491 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

This was referenced Sep 6, 2018
2018-09-06 Version 10.10.0 (Current) @targos beevelop/docker-android-nodejs#236
Closed
2018-09-06 Version 10.10.0 (Current) @targos beevelop/docker-nodejs#221
Closed

vsemozhetbyt mentioned this pull request Sep 24, 2018
process,tty: allow reading/writing from duplex sockets #23053
Closed
4 tasks


		Used to prevent an abort if a string decoder was set on the Socket.

		Example

Uh oh!

Uh oh!

Conversation

SirR4T commented Aug 3, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

List of errors to be documented as removed (from #21491)

Uh oh!

vsemozhetbyt 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!

vsemozhetbytAug 3, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

vsemozhetbytAug 6, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SirR4TAug 7, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joyeecheungAug 8, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

SirR4TAug 22, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joyeecheungAug 23, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vsemozhetbyt commented Aug 7, 2018

Uh oh!

SirR4T commented Aug 8, 2018

Uh oh!

vsemozhetbyt left a comment

Choose a reason for hiding this comment

Uh oh!

SirR4T commented Aug 22, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

joyeecheung commented Aug 23, 2018

Uh oh!

SirR4T commented Aug 24, 2018

Uh oh!

vsemozhetbyt commented Aug 24, 2018

Uh oh!

joyeecheung commented Aug 24, 2018• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SirR4T commented Aug 3, 2018•
edited
Loading

vsemozhetbytAug 3, 2018•
edited
Loading

vsemozhetbytAug 6, 2018•
edited
Loading

SirR4TAug 7, 2018•
edited
Loading

joyeecheungAug 8, 2018•
edited
Loading

SirR4TAug 22, 2018•
edited
Loading

joyeecheungAug 23, 2018•
edited
Loading

SirR4T commented Aug 22, 2018•
edited
Loading

joyeecheung commented Aug 24, 2018•
edited
Loading