From 0546c6a79bb61d58e75dd4a5381929dd02fa2662 Mon Sep 17 00:00:00 2001 From: Sarat Addepalli Date: Thu, 2 Aug 2018 12:28:19 +0530 Subject: [PATCH 1/9] [WIP] error: documenting removed error codes. --- doc/api/errors.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/doc/api/errors.md b/doc/api/errors.md index 72e61c49bb970a..ac9c8b0db8bf4d 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -1848,6 +1848,21 @@ Creation of a [`zlib`][] object failed due to incorrect configuration. A module file could not be resolved while attempting a [`require()`][] or `import` operation. + +### ERR_FS_WATCHER_ALREADY_STARTED + +An attempt was made to start a watcher returned by `fs.watch()` that has already been started. + + +### ERR_FS_WATCHER_NOT_STARTED + + +An attempt was made to initiate operations on a watcher returned by `fs.watch()` that has not yet been started. + [`--force-fips`]: cli.html#cli_force_fips [`'uncaughtException'`]: process.html#process_event_uncaughtexception [`child_process`]: child_process.html @@ -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 [V8's stack trace API]: https://github.com/v8/v8/wiki/Stack-Trace-API [WHATWG URL API]: url.html#url_the_whatwg_url_api [crypto digest algorithm]: crypto.html#crypto_crypto_gethashes From 25a533f011e88d266560aa3089b06098268496c9 Mon Sep 17 00:00:00 2001 From: Sarat Addepalli Date: Mon, 6 Aug 2018 11:20:19 +0530 Subject: [PATCH 2/9] doc: fix linter issues for legacy error codes --- doc/api/errors.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index ac9c8b0db8bf4d..9a4ef9bb026426 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -1848,12 +1848,16 @@ Creation of a [`zlib`][] object failed due to incorrect configuration. A module file could not be resolved while attempting a [`require()`][] or `import` operation. + +## Legacy Node.js Error Codes + ### ERR_FS_WATCHER_ALREADY_STARTED -An attempt was made to start a watcher returned by `fs.watch()` that has already been started. +An attempt was made to start a watcher returned by `fs.watch()` that has +already been started. ### ERR_FS_WATCHER_NOT_STARTED @@ -1861,7 +1865,8 @@ An attempt was made to start a watcher returned by `fs.watch()` that has already added: v10.0.0 --> -An attempt was made to initiate operations on a watcher returned by `fs.watch()` that has not yet been started. +An attempt was made to initiate operations on a watcher returned by +`fs.watch()` that has not yet been started. [`--force-fips`]: cli.html#cli_force_fips [`'uncaughtException'`]: process.html#process_event_uncaughtexception From 208cb4fd9c28f29ccadca5b23e6e42c80ac17504 Mon Sep 17 00:00:00 2001 From: Sarat Addepalli Date: Mon, 6 Aug 2018 11:26:31 +0530 Subject: [PATCH 3/9] doc: Fix linter issues in errors.md --- doc/api/errors.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index 9a4ef9bb026426..2a6423eff537c2 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -1910,7 +1910,6 @@ An attempt was made to initiate operations on a watcher returned by [`zlib`]: zlib.html [ES6 module]: esm.html [Node.js Error Codes]: #nodejs-error-codes -[Legacy Node.js Error Codes]: #legacy-nodejs-error-codes [V8's stack trace API]: https://github.com/v8/v8/wiki/Stack-Trace-API [WHATWG URL API]: url.html#url_the_whatwg_url_api [crypto digest algorithm]: crypto.html#crypto_crypto_gethashes From 9b53c58b05182093e8d9d5b771b9c73485bad79f Mon Sep 17 00:00:00 2001 From: Sarat Addepalli Date: Tue, 7 Aug 2018 10:30:26 +0530 Subject: [PATCH 4/9] doc: add YAML parsers for removed sections --- doc/api/errors.md | 2 ++ tools/doc/common.js | 4 ++++ tools/doc/html.js | 10 +++++++++- 3 files changed, 15 insertions(+), 1 deletion(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index 2a6423eff537c2..4fe1a7ac509e3b 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -1855,6 +1855,7 @@ A module file could not be resolved while attempting a [`require()`][] or ### ERR_FS_WATCHER_ALREADY_STARTED An attempt was made to start a watcher returned by `fs.watch()` that has already been started. @@ -1863,6 +1864,7 @@ already been started. ### ERR_FS_WATCHER_NOT_STARTED An attempt was made to initiate operations on a watcher returned by diff --git a/tools/doc/common.js b/tools/doc/common.js index 4dfadd353d9ec8..7d8aefb65d84fd 100644 --- a/tools/doc/common.js +++ b/tools/doc/common.js @@ -34,6 +34,10 @@ function extractAndParseYAML(text) { meta.deprecated = arrify(meta.deprecated); } + if (meta.removed) { + meta.removed = arrify(meta.removed); + } + meta.changes = meta.changes || []; return meta; diff --git a/tools/doc/html.js b/tools/doc/html.js index d65a4b323aef36..f1ac9e144e61e1 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -264,6 +264,7 @@ function parseYAML(text) { const added = { description: '' }; const deprecated = { description: '' }; + const removed = { description: '' }; if (meta.added) { added.version = meta.added.join(', '); @@ -276,9 +277,15 @@ function parseYAML(text) { `Deprecated since: ${deprecated.version}`; } + if (meta.removed) { + removed.version = meta.removed.join(', '); + removed.description = `Removed in: ${removed.version}`; + } + if (meta.changes.length > 0) { if (added.description) meta.changes.push(added); if (deprecated.description) meta.changes.push(deprecated); + if (removed.description) meta.changes.push(removed); meta.changes.sort((a, b) => versionSort(a.version, b.version)); @@ -299,7 +306,8 @@ function parseYAML(text) { result += '\n\n'; } else { - result += `${added.description}${deprecated.description}\n`; + result += `${added.description}${deprecated.description}` + + `${removed.description}\n`; } if (meta.napiVersion) { From dd31ede487d7981ea67c4a28e32fe20a3520e4d8 Mon Sep 17 00:00:00 2001 From: Sarat Addepalli Date: Thu, 23 Aug 2018 09:45:59 +0530 Subject: [PATCH 5/9] doc: update list of deprecated / removed error codes --- doc/api/errors.md | 227 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 225 insertions(+), 2 deletions(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index 4fe1a7ac509e3b..3e516c7e4b1d69 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -1851,11 +1851,14 @@ A module file could not be resolved while attempting a [`require()`][] or ## Legacy Node.js Error Codes +> Stability: 0 - Deprecated. These error codes are either inconsistent, or have +> been removed. + ### ERR_FS_WATCHER_ALREADY_STARTED An attempt was made to start a watcher returned by `fs.watch()` that has already been started. @@ -1864,12 +1867,231 @@ already been started. ### ERR_FS_WATCHER_NOT_STARTED An attempt was made to initiate operations on a watcher returned by `fs.watch()` that has not yet been started. + +### ERR_HTTP2_ALREADY_SHUTDOWN + + +Occurs with multiple attempts to shutdown an HTTP/2 session. + + +### ERR_HTTP2_ERROR + + +A non-specific HTTP/2 error has occurred. + + +### ERR_HTTP2_FRAME_ERROR + + +Used when a failure occurs sending an individual frame on the HTTP/2 +session. + + +### ERR_HTTP2_HEADERS_OBJECT + + +Used when an HTTP/2 Headers Object is expected. + + +### ERR_HTTP2_HEADER_REQUIRED + + +Used when a required header is missing in an HTTP/2 message. + + +### ERR_HTTP2_INFO_HEADERS_AFTER_RESPOND + + +HTTP/2 Informational headers must only be sent *prior* to calling the +`Http2Stream.prototype.respond()` method. + + +### ERR_HTTP2_STREAM_CLOSED + + +Used when an action has been performed on an HTTP/2 Stream that has already +been closed. + + +### ERR_HTTP_INVALID_CHAR + + +Used when an invalid character is found in an HTTP response status message +(reason phrase). + + +### ERR_INVALID_ARRAY_LENGTH + + +Used when an Array is not of the expected length or in a valid range. + + +### ERR_INVALID_DOMAIN_NAME + + +Used when `hostname` can not be parsed from a provided URL. + + +### ERR_INVALID_REPL_HISTORY + + +Used in the `repl` in case the old history file is used and an error occurred +while trying to read and parse it. + + +### ERR_MISSING_DYNAMIC_INSTANTIATE_HOOK + + +Used when an [ES6 module][] loader hook specifies `format: 'dynamic'` but does +not provide a `dynamicInstantiate` hook. + + +### ERR_NAPI_CONS_PROTOTYPE_OBJECT + + +Used by the `N-API` when `Constructor.prototype` is not an object. + + +### ERR_OUTOFMEMORY + + +Used generically to identify that an operation caused an out of memory +condition. + + +### ERR_PARSE_HISTORY_DATA + + +The `repl` module was unable parse data from the REPL history file. + + +### ERR_STREAM_HAS_STRINGDECODER + + +Used to prevent an abort if a string decoder was set on the Socket. + +Example +```js +const Socket = require('net').Socket; +const instance = new Socket(); + +instance.setEncoding('utf-8'); +``` + + +### ERR_STREAM_READ_NOT_IMPLEMENTED + + +Used when an attempt is made to use a readable stream that has not implemented +[`readable._read()`][]. + + +### ERR_STRING_TOO_LARGE + + +An attempt has been made to create a string larger than the maximum allowed +size. + + +### ERR_TLS_RENEGOTIATION_FAILED + + +Used when a TLS renegotiation request has failed in a non-specific way. + + +### ERR_UNKNOWN_BUILTIN_MODULE + + +The `'ERR_UNKNOWN_BUILTIN_MODULE'` error code is used to identify a specific +kind of internal Node.js error that should not typically be triggered by user +code. Instances of this error point to an internal bug within the Node.js +binary itself. + + +### ERR_VALUE_OUT_OF_RANGE + + +Used when a given value is out of the accepted range. + + +### ERR_ZLIB_BINDING_CLOSED + + +Used when an attempt is made to use a `zlib` object after it has already been +closed. + [`--force-fips`]: cli.html#cli_force_fips [`'uncaughtException'`]: process.html#process_event_uncaughtexception [`child_process`]: child_process.html @@ -1897,6 +2119,7 @@ An attempt was made to initiate operations on a watcher returned by [`new URLSearchParams(iterable)`]: url.html#url_constructor_new_urlsearchparams_iterable [`process.send()`]: process.html#process_process_send_message_sendhandle_options_callback [`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn +[`readable._read()`]: stream.html#stream_readable_read_size_1 [`require()`]: modules.html#modules_require [`require('crypto').setEngine()`]: crypto.html#crypto_crypto_setengine_engine_flags [`server.listen()`]: net.html#net_server_listen From 1ad00f2ab592c36c65192c06b6aef70d948e0772 Mon Sep 17 00:00:00 2001 From: Sarat Addepalli Date: Fri, 24 Aug 2018 09:29:13 +0530 Subject: [PATCH 6/9] docs: fix typos in error docs --- doc/api/errors.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index 3e516c7e4b1d69..3c0c72cfa65a39 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -1926,7 +1926,7 @@ added: v9.0.0 removed: v10.0.0 --> -HTTP/2 Informational headers must only be sent *prior* to calling the +HTTP/2 informational headers must only be sent *prior* to calling the `Http2Stream.prototype.respond()` method. @@ -1965,7 +1965,7 @@ added: v9.0.0 removed: REPLACEME --> -Used when `hostname` can not be parsed from a provided URL. +Used when `hostname` cannot be parsed from a provided URL. ### ERR_INVALID_REPL_HISTORY @@ -2013,7 +2013,7 @@ added: v9.0.0 removed: v10.0.0 --> -The `repl` module was unable parse data from the REPL history file. +The `repl` module was unable to parse data from the REPL history file. ### ERR_STREAM_HAS_STRINGDECODER @@ -2024,12 +2024,11 @@ removed: v9.0.0 Used to prevent an abort if a string decoder was set on the Socket. -Example ```js const Socket = require('net').Socket; const instance = new Socket(); -instance.setEncoding('utf-8'); +instance.setEncoding('utf8'); ``` From e77d298873934bb587b65ff554b1cf94c2e2a72d Mon Sep 17 00:00:00 2001 From: Sarat Addepalli Date: Fri, 24 Aug 2018 09:31:08 +0530 Subject: [PATCH 7/9] doc: errors that have been removed but not released Documentation can be added once the PRs land on a release. Do not add documentation for those error codes yet. [See point 2 here](https://github.com/nodejs/node/pull/22100#issuecomment-415558055). --- doc/api/errors.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index 3c0c72cfa65a39..c8d7b1fef2177f 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -1949,24 +1949,6 @@ removed: v10.0.0 Used when an invalid character is found in an HTTP response status message (reason phrase). - -### ERR_INVALID_ARRAY_LENGTH - - -Used when an Array is not of the expected length or in a valid range. - - -### ERR_INVALID_DOMAIN_NAME - - -Used when `hostname` cannot be parsed from a provided URL. - ### ERR_INVALID_REPL_HISTORY -An attempt was made to start a watcher returned by `fs.watch()` that has -already been started. - - -### ERR_FS_WATCHER_NOT_STARTED - - -An attempt was made to initiate operations on a watcher returned by -`fs.watch()` that has not yet been started. - - -### ERR_HTTP2_ALREADY_SHUTDOWN - - -Occurs with multiple attempts to shutdown an HTTP/2 session. - - -### ERR_HTTP2_ERROR - - -A non-specific HTTP/2 error has occurred. - ### ERR_HTTP2_FRAME_ERROR - -Used in the `repl` in case the old history file is used and an error occurred -while trying to read and parse it. - - -### ERR_MISSING_DYNAMIC_INSTANTIATE_HOOK - - -Used when an [ES6 module][] loader hook specifies `format: 'dynamic'` but does -not provide a `dynamicInstantiate` hook. - ### ERR_NAPI_CONS_PROTOTYPE_OBJECT - -Used to prevent an abort if a string decoder was set on the Socket. - -```js -const Socket = require('net').Socket; -const instance = new Socket(); - -instance.setEncoding('utf8'); -``` - ### ERR_STREAM_READ_NOT_IMPLEMENTED - -An attempt has been made to create a string larger than the maximum allowed -size. - ### ERR_TLS_RENEGOTIATION_FAILED