error: document removed error codes #22100

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

doc/api/errors.md

+<!-- YAML
+added: v10.0.0
+-->
+An attempt was made to start a watcher returned by `fs.watch()` that has already been started.


Linter issue: 80 characters per line limit exceeded.

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

doc/api/errors.md

+added: v10.0.0
+-->
+
+An attempt was made to initiate operations on a watcher returned by `fs.watch()` that has not yet been started.


Linter issue: 80 characters per line limit exceeded.

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

doc/api/errors.md

@@ -1890,6 +1905,7 @@ A module file could not be resolved while attempting a [`require()`][] or
 [`zlib`]: zlib.html
 [ES6 module]: esm.html
 [Node.js Error Codes]: #nodejs-error-codes
+[Legacy Node.js Error Codes]: #legacy-nodejs-error-codes


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

doc/api/errors.md

@@ -1847,20 +1847,25 @@ Creation of a [`zlib`][] object failed due to incorrect configuration.
 A module file could not be resolved while attempting a [`require()`][] or
 `import` operation.

+<a id="legacy-nodejs-error-codes"></a>


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

doc/api/errors.md

+<a id="ERR_FS_WATCHER_ALREADY_STARTED"></a>
+### ERR_FS_WATCHER_ALREADY_STARTED
+<!-- YAML
+added: v10.0.0


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

function extractAndParseYAML(text) {

node/tools/doc/html.js

Line 258 in 2bea9ce

function parseYAML(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

doc/api/errors.md

+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

doc/api/errors.md

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


can not -> cannot

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

doc/api/errors.md

+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

doc/api/errors.md

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

doc/api/errors.md

+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

doc/api/errors.md

@@ -2073,6 +1990,64 @@ removed: v10.0.0
 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

tools/doc/common.js

@@ -34,6 +34,10 @@ function extractAndParseYAML(text) {
    meta.deprecated = arrify(meta.deprecated);
  }

+  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: #22100 Fixes: #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: #22100 Fixes: #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: #22100 Fixes: #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: #22100 Fixes: #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 cbe275c Compare 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 0c11e4d Compare August 7, 2018 04:45

vsemozhetbyt approved these changes Aug 8, 2018

View reviewed changes

SirR4T and 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 dd31ede Compare August 23, 2018 05:15

SirR4T changed the title ~~[WIP] error: document removed error codes~~ error: document removed error codes Aug 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: #22100 Fixes: #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: #22100 Fixes: #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: #22100 Fixes: #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: #22100 Fixes: #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

error: document removed error codes #22100

error: document removed error codes #22100

Conversation

SirR4T commented Aug 3, 2018 • edited Loading

Checklist

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

vsemozhetbyt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt Aug 3, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt Aug 6, 2018 • edited Loading

Choose a reason for hiding this comment

SirR4T Aug 7, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joyeecheung Aug 8, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SirR4T Aug 22, 2018 • edited Loading

Choose a reason for hiding this comment

joyeecheung Aug 23, 2018 • edited Loading

Choose a reason for hiding this comment

vsemozhetbyt commented Aug 7, 2018

SirR4T commented Aug 8, 2018

vsemozhetbyt left a comment

Choose a reason for hiding this comment

SirR4T commented Aug 22, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joyeecheung commented Aug 23, 2018

SirR4T commented Aug 24, 2018

vsemozhetbyt commented Aug 24, 2018

joyeecheung commented Aug 24, 2018 • edited Loading

SirR4T commented Aug 25, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt commented Aug 25, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joyeecheung left a comment

Choose a reason for hiding this comment

joyeecheung commented Aug 26, 2018

vsemozhetbyt commented Aug 26, 2018

SirR4T commented Aug 3, 2018 •

edited

Loading

vsemozhetbyt Aug 3, 2018 •

edited

Loading

vsemozhetbyt Aug 6, 2018 •

edited

Loading

SirR4T Aug 7, 2018 •

edited

Loading

joyeecheung Aug 8, 2018 •

edited

Loading

SirR4T Aug 22, 2018 •

edited

Loading

joyeecheung Aug 23, 2018 •

edited

Loading

SirR4T commented Aug 22, 2018 •

edited

Loading

joyeecheung commented Aug 24, 2018 •

edited

Loading