From a8533cf543537b7c17f267e96e93640b7c3f3f5e Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Date: Mon, 9 Apr 2018 19:30:22 +0300 Subject: [PATCH] doc: add quotes for event names + fix similar nits PR-URL: https://github.com/nodejs/node/pull/19915 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> --- doc/api/assert.md | 4 +-- doc/api/async_hooks.md | 8 ++--- doc/api/child_process.md | 22 ++++++------- doc/api/cluster.md | 14 ++++---- doc/api/console.md | 2 +- doc/api/deprecations.md | 2 +- doc/api/dgram.md | 6 ++-- doc/api/documentation.md | 8 ++--- doc/api/domain.md | 30 ++++++++--------- doc/api/errors.md | 6 ++-- doc/api/events.md | 8 ++--- doc/api/fs.md | 6 ++-- doc/api/http.md | 60 +++++++++++++++++----------------- doc/api/http2.md | 14 ++++---- doc/api/https.md | 2 +- doc/api/inspector.md | 6 ++-- doc/api/modules.md | 2 +- doc/api/n-api.md | 4 +-- doc/api/net.md | 42 ++++++++++++------------ doc/api/process.md | 70 ++++++++++++++++++++-------------------- doc/api/readline.md | 14 ++++---- doc/api/stream.md | 37 ++++++++++----------- doc/api/timers.md | 4 +-- doc/api/tls.md | 5 +-- doc/api/util.md | 3 +- doc/api/zlib.md | 8 ++--- 26 files changed, 194 insertions(+), 193 deletions(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index ff06c9250f7da3..6a587052f2307c 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -561,8 +561,8 @@ added: v0.1.21 changes: - version: REPLACEME pr-url: https://github.com/nodejs/node/pull/18418 - description: Calling `assert.fail` with more than one argument is deprecated - and emits a warning. + description: Calling `assert.fail()` with more than one argument is + deprecated and emits a warning. --> * `actual` {any} * `expected` {any} diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 1f0ffe766e1977..63c5f1c8198434 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -15,9 +15,9 @@ const async_hooks = require('async_hooks'); ## Terminology An asynchronous resource represents an object with an associated callback. -This callback may be called multiple times, for example, the `connection` event -in `net.createServer`, or just a single time like in `fs.open`. A resource -can also be closed before the callback is called. AsyncHook does not +This callback may be called multiple times, for example, the `'connection'` +event in `net.createServer()`, or just a single time like in `fs.open()`. +A resource can also be closed before the callback is called. AsyncHook does not explicitly distinguish between these different cases but will represent them as the abstract concept that is a resource. @@ -128,7 +128,7 @@ const asyncHook = async_hooks.createHook(new MyAddedCallbacks()); If any `AsyncHook` callbacks throw, the application will print the stack trace and exit. The exit path does follow that of an uncaught exception, but -all `uncaughtException` listeners are removed, thus forcing the process to +all `'uncaughtException'` listeners are removed, thus forcing the process to exit. The `'exit'` callbacks will still be called unless the application is run with `--abort-on-uncaught-exception`, in which case a stack trace will be printed and the application exits, leaving a core file. diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 1ebd3cee199e4a..ecfda860ea2f1a 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -608,9 +608,8 @@ pipes between the parent and child. The value is one of the following: between parent and child. A [`ChildProcess`][] may have at most *one* IPC stdio file descriptor. Setting this option enables the [`subprocess.send()`][] method. If the child is a Node.js process, the presence of an IPC channel - will enable [`process.send()`][], [`process.disconnect()`][], - [`process.on('disconnect')`][], and [`process.on('message')`] within the - child. + will enable [`process.send()`][] and [`process.disconnect()`][] methods, + as well as [`'disconnect'`][] and [`'message'`][] events within the child. Accessing the IPC channel fd in any way other than [`process.send()`][] or using the IPC channel with a child process that is not a Node.js instance @@ -651,8 +650,8 @@ spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] }); *It is worth noting that when an IPC channel is established between the parent and child processes, and the child is a Node.js process, the child is launched with the IPC channel unreferenced (using `unref()`) until the -child registers an event handler for the [`process.on('disconnect')`][] event -or the [`process.on('message')`][] event. This allows the child to exit +child registers an event handler for the [`'disconnect'`][] event +or the [`'message'`][] event. This allows the child to exit normally without the process being held open by the open IPC channel.* See also: [`child_process.exec()`][] and [`child_process.fork()`][] @@ -1103,8 +1102,7 @@ changes: When an IPC channel has been established between the parent and child ( i.e. when using [`child_process.fork()`][]), the `subprocess.send()` method can be used to send messages to the child process. When the child process is a -Node.js instance, these messages can be received via the -[`process.on('message')`][] event. +Node.js instance, these messages can be received via the [`'message'`][] event. The message goes through serialization and parsing. The resulting message might not be the same as what is originally sent. @@ -1139,16 +1137,16 @@ allows the child to send messages back to the parent. There is a special case when sending a `{cmd: 'NODE_foo'}` message. Messages containing a `NODE_` prefix in the `cmd` property are reserved for use within -Node.js core and will not be emitted in the child's [`process.on('message')`][] +Node.js core and will not be emitted in the child's [`'message'`][] event. Rather, such messages are emitted using the -`process.on('internalMessage')` event and are consumed internally by Node.js. +`'internalMessage'` event and are consumed internally by Node.js. Applications should avoid using such messages or listening for `'internalMessage'` events as it is subject to change without notice. The optional `sendHandle` argument that may be passed to `subprocess.send()` is for passing a TCP server or socket object to the child process. The child will receive the object as the second argument passed to the callback function -registered on the [`process.on('message')`][] event. Any data that is received +registered on the [`'message'`][] event. Any data that is received and buffered in the socket will not be sent to the child. The optional `callback` is a function that is invoked after the message is @@ -1363,8 +1361,10 @@ the same requirement. Thus, in `child_process` functions where a shell can be spawned, `'cmd.exe'` is used as a fallback if `process.env.ComSpec` is unavailable. +[`'disconnect'`]: process.html#process_event_disconnect [`'error'`]: #child_process_event_error [`'exit'`]: #child_process_event_exit +[`'message'`]: process.html#process_event_message [`ChildProcess`]: #child_process_child_process [`Error`]: errors.html#errors_class_error [`EventEmitter`]: events.html#events_class_eventemitter @@ -1389,8 +1389,6 @@ unavailable. [`process.disconnect()`]: process.html#process_process_disconnect [`process.env`]: process.html#process_process_env [`process.execPath`]: process.html#process_process_execpath -[`process.on('disconnect')`]: process.html#process_event_disconnect -[`process.on('message')`]: process.html#process_event_message [`process.send()`]: process.html#process_process_send_message_sendhandle_options_callback [`stdio`]: #child_process_options_stdio [`util.promisify()`]: util.html#util_util_promisify_original diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 5f5273d37301c4..04b9eac46c8a92 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -192,7 +192,7 @@ added: v0.7.0 * `message` {Object} * `handle` {undefined|Object} -Similar to the `cluster.on('message')` event, but specific to this worker. +Similar to the `'message'` event of `cluster`, but specific to this worker. Within a worker, `process.on('message')` may also be used. @@ -463,7 +463,7 @@ added: v0.7.9 Emitted after the worker IPC channel has disconnected. This can occur when a worker exits gracefully, is killed, or is disconnected manually (such as with -worker.disconnect()). +`worker.disconnect()`). There may be a delay between the `'disconnect'` and `'exit'` events. These events can be used to detect if the process is stuck in a cleanup or if there @@ -497,7 +497,7 @@ cluster.on('exit', (worker, code, signal) => { }); ``` -See [child_process event: 'exit'][]. +See [child_process event: `'exit'`][]. ## Event: 'fork' <!-- YAML @@ -573,7 +573,7 @@ changes: Emitted when the cluster master receives a message from any worker. -See [child_process event: 'message'][]. +See [child_process event: `'message'`][]. Before Node.js v6.0, this event emitted only the message and the handle, but not the worker object, contrary to what the documentation stated. @@ -603,7 +603,7 @@ added: v0.7.0 After forking a new worker, the worker should respond with an online message. When the master receives an online message it will emit this event. The difference between `'fork'` and `'online'` is that fork is emitted when the -master forks a worker, and 'online' is emitted when the worker is running. +master forks a worker, and `'online'` is emitted when the worker is running. ```js cluster.on('online', (worker) => { @@ -846,6 +846,6 @@ socket.on('data', (id) => { [`server.close()`]: net.html#net_event_close [`worker.exitedAfterDisconnect`]: #cluster_worker_exitedafterdisconnect [Child Process module]: child_process.html#child_process_child_process_fork_modulepath_args_options -[child_process event: 'exit']: child_process.html#child_process_event_exit -[child_process event: 'message']: child_process.html#child_process_event_message +[child_process event: `'exit'`]: child_process.html#child_process_event_exit +[child_process event: `'message'`]: child_process.html#child_process_event_message [`cluster.settings`]: #cluster_cluster_settings diff --git a/doc/api/console.md b/doc/api/console.md index 53395d8ef6f2d6..d9736a7c9f1f15 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -492,7 +492,7 @@ added: v8.0.0 * `label` {string} This method does not display anything unless used in the inspector. The -`console.timeStamp()` method adds an event with the label `label` to the +`console.timeStamp()` method adds an event with the label `'label'` to the **Timeline** panel of the inspector. ### console.timeline([label]) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index d66d16e000f81b..74ebfda61f9b10 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -806,7 +806,7 @@ API instead. Type: End-of-Life -`runInAsyncIdScope` doesn't emit the `before` or `after` event and can thus +`runInAsyncIdScope` doesn't emit the `'before'` or `'after'` event and can thus cause a lot of issues. See https://github.com/nodejs/node/issues/14328 for more details. diff --git a/doc/api/dgram.md b/doc/api/dgram.md index 4962feef923d1a..06c15ffa25c879 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -605,13 +605,13 @@ and port can be retrieved using [`socket.address().address`][] and added: v0.1.99 --> -* `type` {string} - Either 'udp4' or 'udp6'. +* `type` {string} - Either `'udp4'` or `'udp6'`. * `callback` {Function} - Attached as a listener to `'message'` events. * Returns: {dgram.Socket} Creates a `dgram.Socket` object of the specified `type`. The `type` argument -can be either `udp4` or `udp6`. An optional `callback` function can be passed -which is added as a listener for `'message'` events. +can be either `'udp4'` or `'udp6'`. An optional `callback` function can be +passed which is added as a listener for `'message'` events. Once the socket is created, calling [`socket.bind()`][] will instruct the socket to begin listening for datagram messages. When `address` and `port` are diff --git a/doc/api/documentation.md b/doc/api/documentation.md index 33da3a45e77d36..0cd84a9f62042e 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -63,7 +63,7 @@ failures or behavior changes when API modifications occur. To help avoid such surprises, `Experimental` features may require a command-line flag to explicitly enable them, or may cause a process warning to be emitted. By default, such warnings are printed to [`stderr`][] and may be handled by -attaching a listener to the [`process.on('warning')`][] event. +attaching a listener to the [`'warning'`][] event. ## JSON Output <!-- YAML @@ -94,9 +94,9 @@ relative to Linux and macOS. For an example of the subtle ways in which it's sometimes impossible to replace Unix syscall semantics on Windows, see [Node issue 4760](https://github.com/nodejs/node/issues/4760). -[submit an issue]: https://github.com/nodejs/node/issues/new -[the contributing guide]: https://github.com/nodejs/node/blob/master/CONTRIBUTING.md +[`'warning'`]: process.html#process_event_warning [`stderr`]: process.html#process_process_stderr -[`process.on('warning')`]: process.html#process_event_warning [`fs.open()`]: fs.html#fs_fs_open_path_flags_mode_callback [`fs.lchown()`]: fs.html#fs_fs_lchown_path_uid_gid_callback +[submit an issue]: https://github.com/nodejs/node/issues/new +[the contributing guide]: https://github.com/nodejs/node/blob/master/CONTRIBUTING.md diff --git a/doc/api/domain.md b/doc/api/domain.md index a2c7a9f90e649b..4db649af78dbe4 100644 --- a/doc/api/domain.md +++ b/doc/api/domain.md @@ -299,7 +299,7 @@ binding. This also works with timers that are returned from [`setInterval()`][] and [`setTimeout()`][]. If their callback function throws, it will be caught by -the domain 'error' handler. +the domain `'error'` handler. If the Timer or EventEmitter was already bound to a domain, it is removed from that one, and bound to this one instead. @@ -334,30 +334,30 @@ d.on('error', (er) => { ### domain.enter() -The `enter` method is plumbing used by the `run`, `bind`, and `intercept` -methods to set the active domain. It sets `domain.active` and `process.domain` -to the domain, and implicitly pushes the domain onto the domain stack managed -by the domain module (see [`domain.exit()`][] for details on the domain stack). -The call to `enter` delimits the beginning of a chain of asynchronous calls and -I/O operations bound to a domain. +The `enter()` method is plumbing used by the `run()`, `bind()`, and +`intercept()` methods to set the active domain. It sets `domain.active` and +`process.domain` to the domain, and implicitly pushes the domain onto the domain +stack managed by the domain module (see [`domain.exit()`][] for details on the +domain stack). The call to `enter()` delimits the beginning of a chain of +asynchronous calls and I/O operations bound to a domain. -Calling `enter` changes only the active domain, and does not alter the domain -itself. `enter` and `exit` can be called an arbitrary number of times on a +Calling `enter()` changes only the active domain, and does not alter the domain +itself. `enter()` and `exit()` can be called an arbitrary number of times on a single domain. ### domain.exit() -The `exit` method exits the current domain, popping it off the domain stack. +The `exit()` method exits the current domain, popping it off the domain stack. Any time execution is going to switch to the context of a different chain of asynchronous calls, it's important to ensure that the current domain is exited. -The call to `exit` delimits either the end of or an interruption to the chain +The call to `exit()` delimits either the end of or an interruption to the chain of asynchronous calls and I/O operations bound to a domain. If there are multiple, nested domains bound to the current execution context, -`exit` will exit any domains nested within this domain. +`exit()` will exit any domains nested within this domain. -Calling `exit` changes only the active domain, and does not alter the domain -itself. `enter` and `exit` can be called an arbitrary number of times on a +Calling `exit()` changes only the active domain, and does not alter the domain +itself. `enter()` and `exit()` can be called an arbitrary number of times on a single domain. ### domain.intercept(callback) @@ -481,7 +481,7 @@ d2.run(() => { ``` Note that domains will not interfere with the error handling mechanisms for -Promises, i.e. no `error` event will be emitted for unhandled Promise +Promises, i.e. no `'error'` event will be emitted for unhandled Promise rejections. [`Error`]: errors.html#errors_class_error diff --git a/doc/api/errors.md b/doc/api/errors.md index 3424afa12c3967..3923780defa1e7 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -109,7 +109,7 @@ For *all* [`EventEmitter`][] objects, if an `'error'` event handler is not provided, the error will be thrown, causing the Node.js process to report an unhandled exception and crash unless either: The [`domain`][domains] module is used appropriately or a handler has been registered for the -[`process.on('uncaughtException')`][] event. +[`'uncaughtException'`][] event. ```js const EventEmitter = require('events'); @@ -1438,7 +1438,7 @@ An attempt was made to use a readable stream that did not implement <a id="ERR_STREAM_UNSHIFT_AFTER_END_EVENT"></a> ### ERR_STREAM_UNSHIFT_AFTER_END_EVENT -An attempt was made to call [`stream.unshift()`][] after the `end` event was +An attempt was made to call [`stream.unshift()`][] after the `'end'` event was emitted. <a id="ERR_STREAM_WRAP"></a> @@ -1656,6 +1656,7 @@ meaning of the error depends on the specific function. Creation of a [`zlib`][] object failed due to incorrect configuration. +[`'uncaughtException'`]: process.html#process_event_uncaughtexception [`--force-fips`]: cli.html#cli_force_fips [`child_process`]: child_process.html [`cipher.getAuthTag()`]: crypto.html#crypto_cipher_getauthtag @@ -1687,7 +1688,6 @@ Creation of a [`zlib`][] object failed due to incorrect configuration. [`net`]: net.html [`new URL(input)`]: url.html#url_constructor_new_url_input_base [`new URLSearchParams(iterable)`]: url.html#url_constructor_new_urlsearchparams_iterable -[`process.on('uncaughtException')`]: process.html#process_event_uncaughtexception [`process.send()`]: process.html#process_process_send_message_sendhandle_options_callback [`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn [`require('crypto').setEngine()`]: crypto.html#crypto_crypto_setengine_engine_flags diff --git a/doc/api/events.md b/doc/api/events.md index 5cb7b90b8d844a..a5a45ca3de4834 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -522,9 +522,9 @@ server.on('connection', callback); server.removeListener('connection', callback); ``` -`removeListener` will remove, at most, one instance of a listener from the +`removeListener()` will remove, at most, one instance of a listener from the listener array. If any single listener has been added multiple times to the -listener array for the specified `eventName`, then `removeListener` must be +listener array for the specified `eventName`, then `removeListener()` must be called multiple times to remove each instance. Note that once an event has been emitted, all listeners attached to it at the @@ -596,7 +596,7 @@ added: v9.4.0 - Returns: {Function[]} Returns a copy of the array of listeners for the event named `eventName`, -including any wrappers (such as those created by `.once`). +including any wrappers (such as those created by `.once()`). ```js const emitter = new EventEmitter(); @@ -614,7 +614,7 @@ logFnWrapper.listener(); logFnWrapper(); emitter.on('log', () => console.log('log persistently')); -// will return a new Array with a single function bound by `on` above +// will return a new Array with a single function bound by `.on()` above const newListeners = emitter.rawListeners('log'); // logs "log persistently" twice diff --git a/doc/api/fs.md b/doc/api/fs.md index 1adae9b1236dc6..368193024628a1 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -311,7 +311,7 @@ support. If `filename` is provided, it will be provided as a `Buffer` if `filename` will be a UTF-8 string. ```js -// Example when handled through fs.watch listener +// Example when handled through fs.watch() listener fs.watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => { if (filename) { console.log(filename); @@ -1323,7 +1323,7 @@ to [`net.Socket`][]. If `autoClose` is false, then the file descriptor won't be closed, even if there's an error. It is the application's responsibility to close it and make sure there's no file descriptor leak. If `autoClose` is set to true (default -behavior), on `error` or `end` the file descriptor will be closed +behavior), on `'error'` or `'end'` the file descriptor will be closed automatically. `mode` sets the file mode (permission and sticky bits), but only if the @@ -1386,7 +1386,7 @@ than replacing it may require a `flags` mode of `r+` rather than the default mode `w`. The `encoding` can be any one of those accepted by [`Buffer`][]. -If `autoClose` is set to true (default behavior) on `error` or `end` +If `autoClose` is set to true (default behavior) on `'error'` or `'finish'` the file descriptor will be closed automatically. If `autoClose` is false, then the file descriptor won't be closed, even if there's an error. It is the application's responsibility to close it and make sure there's no diff --git a/doc/api/http.md b/doc/api/http.md index dab18b5539c455..cbedf8c99b07d3 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -661,7 +661,7 @@ added: v0.5.9 * `timeout` {number} Milliseconds before a request times out. * `callback` {Function} Optional function to be called when a timeout occurs. - Same as binding to the `timeout` event. + Same as binding to the `'timeout'` event. * Returns: {http.ClientRequest} Once a socket is assigned to this request and is connected @@ -774,12 +774,12 @@ changes: pr-url: https://github.com/nodejs/node/pull/4557 description: The default action of calling `.destroy()` on the `socket` will no longer take place if there are listeners attached - for `clientError`. + for `'clientError'`. - version: v9.4.0 pr-url: https://github.com/nodejs/node/pull/17672 description: The rawPacket is the current buffer that just parsed. Adding - this buffer to the error object of clientError event is to make - it possible that developers can log the broken packet. + this buffer to the error object of `'clientError'` event is to + make it possible that developers can log the broken packet. --> * `exception` {Error} @@ -1929,7 +1929,7 @@ There are a few special headers that should be noted. * Sending an 'Expect' header will immediately send the request headers. Usually, when sending 'Expect: 100-continue', both a timeout and a listener - for the `continue` event should be set. See RFC2616 Section 8.2.3 for more + for the `'continue'` event should be set. See RFC2616 Section 8.2.3 for more information. * Sending an Authorization header will override using the `auth` option @@ -1948,45 +1948,45 @@ const req = http.request(options, (res) => { In a successful request, the following events will be emitted in the following order: -* `socket` -* `response` - * `data` any number of times, on the `res` object - (`data` will not be emitted at all if the response body is empty, for +* `'socket'` +* `'response'` + * `'data'` any number of times, on the `res` object + (`'data'` will not be emitted at all if the response body is empty, for instance, in most redirects) - * `end` on the `res` object -* `close` + * `'end'` on the `res` object +* `'close'` In the case of a connection error, the following events will be emitted: -* `socket` -* `error` -* `close` +* `'socket'` +* `'error'` +* `'close'` If `req.abort()` is called before the connection succeeds, the following events will be emitted in the following order: -* `socket` +* `'socket'` * (`req.abort()` called here) -* `abort` -* `close` -* `error` with an error with message `Error: socket hang up` and code - `ECONNRESET` +* `'abort'` +* `'close'` +* `'error'` with an error with message `'Error: socket hang up'` and code + `'ECONNRESET'` If `req.abort()` is called after the response is received, the following events will be emitted in the following order: -* `socket` -* `response` - * `data` any number of times, on the `res` object +* `'socket'` +* `'response'` + * `'data'` any number of times, on the `res` object * (`req.abort()` called here) -* `abort` -* `close` - * `aborted` on the `res` object - * `end` on the `res` object - * `close` on the `res` object - -Note that setting the `timeout` option or using the `setTimeout` function will -not abort the request or do anything besides add a `timeout` event. +* `'abort'` +* `'close'` + * `'aborted'` on the `res` object + * `'end'` on the `res` object + * `'close'` on the `res` object + +Note that setting the `timeout` option or using the `setTimeout()` function will +not abort the request or do anything besides add a `'timeout'` event. [`'checkContinue'`]: #http_event_checkcontinue [`'request'`]: #http_event_request diff --git a/doc/api/http2.md b/doc/api/http2.md index d606098eee3f34..0a42dce7e57d05 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -19,8 +19,8 @@ compatibility with the existing [HTTP/1][] module API. However, the [Compatibility API][] is. The `http2` Core API is much more symmetric between client and server than the -`http` API. For instance, most events, like `error`, `connect` and `stream`, can -be emitted either by client-side code or server-side code. +`http` API. For instance, most events, like `'error'`, `'connect'` and +`'stream'`, can be emitted either by client-side code or server-side code. ### Server-side example @@ -463,7 +463,7 @@ If the `payload` argument is not specified, the default payload will be the added: v9.4.0 --> -Calls [`ref()`][`net.Socket.prototype.ref`] on this `Http2Session` +Calls [`ref()`][`net.Socket.prototype.ref()`] on this `Http2Session` instance's underlying [`net.Socket`]. #### http2session.remoteSettings @@ -571,7 +571,7 @@ client. added: v9.4.0 --> -Calls [`unref()`][`net.Socket.prototype.unref`] on this `Http2Session` +Calls [`unref()`][`net.Socket.prototype.unref()`] on this `Http2Session` instance's underlying [`net.Socket`]. ### Class: ServerHttp2Session @@ -856,7 +856,7 @@ added: v8.4.0 --> The `'timeout'` event is emitted after no activity is received for this -`'Http2Stream'` within the number of milliseconds set using +`Http2Stream` within the number of milliseconds set using `http2stream.setTimeout()`. #### Event: 'trailers' @@ -3158,8 +3158,8 @@ following additional properties: [`http2stream.pushStream()`]: #http2_http2stream_pushstream_headers_options_callback [`net.Server.close()`]: net.html#net_server_close_callback [`net.Socket`]: net.html#net_class_net_socket -[`net.Socket.prototype.ref`]: net.html#net_socket_ref -[`net.Socket.prototype.unref`]: net.html#net_socket_unref +[`net.Socket.prototype.ref()`]: net.html#net_socket_ref +[`net.Socket.prototype.unref()`]: net.html#net_socket_unref [`net.connect()`]: net.html#net_net_connect [`request.socket.getPeerCertificate()`]: tls.html#tls_tlssocket_getpeercertificate_detailed [`response.end()`]: #http2_response_end_data_encoding_callback diff --git a/doc/api/https.md b/doc/api/https.md index 0524cd2816de4e..4c8d993ae2b68b 100644 --- a/doc/api/https.md +++ b/doc/api/https.md @@ -67,7 +67,7 @@ added: v0.3.4 --> - `options` {Object} Accepts `options` from [`tls.createServer()`][], [`tls.createSecureContext()`][] and [`http.createServer()`][]. -- `requestListener` {Function} A listener to be added to the `request` event. +- `requestListener` {Function} A listener to be added to the `'request'` event. Example: diff --git a/doc/api/inspector.md b/doc/api/inspector.md index dca182acc6eec6..3883d7c8583c1d 100644 --- a/doc/api/inspector.md +++ b/doc/api/inspector.md @@ -81,7 +81,7 @@ added: v8.0.0 Emitted when an inspector notification is received that has its method field set to the `<inspector-protocol-method>` value. -The following snippet installs a listener on the [`Debugger.paused`][] +The following snippet installs a listener on the [`'Debugger.paused'`][] event, and prints the reason for program suspension whenever program execution is suspended (through breakpoints, for example): @@ -167,8 +167,8 @@ session.post('Profiler.enable', () => { ``` -[`session.connect()`]: #inspector_session_connect -[`Debugger.paused`]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger/#event-paused +[`'Debugger.paused'`]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger#event-paused [`EventEmitter`]: events.html#events_class_eventemitter +[`session.connect()`]: #inspector_session_connect [Chrome DevTools Protocol Viewer]: https://chromedevtools.github.io/devtools-protocol/v8/ [CPU Profiler]: https://chromedevtools.github.io/devtools-protocol/v8/Profiler diff --git a/doc/api/modules.md b/doc/api/modules.md index b1656fcd272ea7..20fb5fab02360f 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -666,7 +666,7 @@ added: v8.9.0 * Returns: {string[]|null} Returns an array containing the paths searched during resolution of `request` or -null if the `request` string references a core module, for example `http` or +`null` if the `request` string references a core module, for example `http` or `fs`. ## The `module` Object diff --git a/doc/api/n-api.md b/doc/api/n-api.md index cece9d1fd154aa..5568130b5ed104 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -550,9 +550,9 @@ napi_status napi_fatal_exception(napi_env env, napi_value err); ``` - `[in] env`: The environment that the API is invoked under. -- `[in] err`: The error you want to pass to `uncaughtException`. +- `[in] err`: The error you want to pass to `'uncaughtException'`. -Trigger an `uncaughtException` in JavaScript. Useful if an async +Trigger an `'uncaughtException'` in JavaScript. Useful if an async callback throws an exception with no way to recover. ### Fatal Errors diff --git a/doc/api/net.md b/doc/api/net.md index 18da052bab8c95..63f798f68cbfb5 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -149,8 +149,8 @@ added: v0.1.90 * Returns: {net.Server} Stops the server from accepting new connections and keeps existing -connections. This function is asynchronous, the server is finally -closed when all connections are ended and the server emits a [`'close'`][] event. +connections. This function is asynchronous, the server is finally closed +when all connections are ended and the server emits a [`'close'`][] event. The optional `callback` will be called once the `'close'` event occurs. Unlike that event, it will be called with an Error as its only argument if the server was not open when it was closed. @@ -206,9 +206,9 @@ on Linux. The default value of this parameter is 511 (not 512). All [`net.Socket`][] are set to `SO_REUSEADDR` (See [socket(7)][] for details). -The `server.listen()` method can be called again if and only if there was an error -during the first `server.listen()` call or `server.close()` has been called. -Otherwise, an `ERR_SERVER_ALREADY_LISTEN` error will be thrown. +The `server.listen()` method can be called again if and only if there was an +error during the first `server.listen()` call or `server.close()` has been +called. Otherwise, an `ERR_SERVER_ALREADY_LISTEN` error will be thrown. One of the most common errors raised when listening is `EADDRINUSE`. This happens when another server is already listening on the requested @@ -346,9 +346,9 @@ added: v0.9.1 * Returns: {net.Server} -Opposite of `unref`, calling `ref` on a previously `unref`d server will *not* -let the program exit if it's the only server left (the default behavior). If -the server is `ref`d calling `ref` again will have no effect. +Opposite of `unref()`, calling `ref()` on a previously `unref`ed server will +*not* let the program exit if it's the only server left (the default behavior). +If the server is `ref`ed calling `ref()` again will have no effect. ### server.unref() <!-- YAML @@ -357,9 +357,9 @@ added: v0.9.1 * Returns: {net.Server} -Calling `unref` on a server will allow the program to exit if this is the only -active server in the event system. If the server is already `unref`d calling -`unref` again will have no effect. +Calling `unref()` on a server will allow the program to exit if this is the only +active server in the event system. If the server is already `unref`ed calling +`unref()` again will have no effect. ## Class: net.Socket <!-- YAML @@ -407,9 +407,9 @@ endpoint, depending on what it [`connect()`][`socket.connect()`] to. added: v0.1.90 --> -* `had_error` {boolean} `true` if the socket had a transmission error. +* `hadError` {boolean} `true` if the socket had a transmission error. -Emitted once the socket is fully closed. The argument `had_error` is a boolean +Emitted once the socket is fully closed. The argument `hadError` is a boolean which says if the socket was closed due to a transmission error. ### Event: 'connect' @@ -425,7 +425,7 @@ See [`net.createConnection()`][]. added: v0.1.90 --> -* {Buffer} +* {Buffer|string} Emitted when data is received. The argument `data` will be a `Buffer` or `String`. Encoding of data is set by [`socket.setEncoding()`][]. @@ -642,7 +642,7 @@ added: v6.1.0 If `true` - [`socket.connect(options[, connectListener])`][`socket.connect(options)`] was called and haven't yet finished. Will be set to `false` before emitting -`connect` event and/or calling +`'connect'` event and/or calling [`socket.connect(options[, connectListener])`][`socket.connect(options)`]'s callback. @@ -709,9 +709,9 @@ added: v0.9.1 * Returns: {net.Socket} The socket itself. -Opposite of `unref`, calling `ref` on a previously `unref`d socket will *not* -let the program exit if it's the only socket left (the default behavior). If -the socket is `ref`d calling `ref` again will have no effect. +Opposite of `unref()`, calling `ref()` on a previously `unref`ed socket will +*not* let the program exit if it's the only socket left (the default behavior). +If the socket is `ref`ed calling `ref` again will have no effect. ### socket.remoteAddress <!-- YAML @@ -816,9 +816,9 @@ added: v0.9.1 * Returns: {net.Socket} The socket itself. -Calling `unref` on a socket will allow the program to exit if this is the only -active socket in the event system. If the socket is already `unref`d calling -`unref` again will have no effect. +Calling `unref()` on a socket will allow the program to exit if this is the only +active socket in the event system. If the socket is already `unref`ed calling +`unref()` again will have no effect. ### socket.write(data[, encoding][, callback]) <!-- YAML diff --git a/doc/api/process.md b/doc/api/process.md index e137ef6a6bd0e1..202725cb515a7d 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -194,7 +194,7 @@ down the process. **It is not safe to resume normal operation after `'uncaughtException'`.** To restart a crashed application in a more reliable way, whether -`uncaughtException` is emitted or not, an external monitor should be employed +`'uncaughtException'` is emitted or not, an external monitor should be employed in a separate process to detect application failures and recover or restart as needed. @@ -272,7 +272,7 @@ lead to sub-optimal application performance, bugs, or security vulnerabilities. The listener function is called with a single `warning` argument whose value is an `Error` object. There are three key properties that describe the warning: -* `name` {string} The name of the warning (currently `Warning` by default). +* `name` {string} The name of the warning (currently `'Warning'` by default). * `message` {string} A system-provided description of the warning. * `stack` {string} A stack trace to the location in the code where the warning was issued. @@ -326,7 +326,7 @@ Using the `--no-deprecation` command line flag will suppress all reporting of the custom deprecation. The `*-deprecation` command line flags only affect warnings that use the name -`DeprecationWarning`. +`'DeprecationWarning'`. #### Emitting custom warnings @@ -340,7 +340,7 @@ custom or application-specific warnings. Signal events will be emitted when the Node.js process receives a signal. Please refer to signal(7) for a listing of standard POSIX signal names such as -`SIGINT`, `SIGHUP`, etc. +`'SIGINT'`, `'SIGHUP'`, etc. The signal handler will receive the signal's name (`'SIGINT'`, `'SIGTERM'`, etc.) as the first argument. @@ -365,37 +365,38 @@ process.on('SIGINT', handle); process.on('SIGTERM', handle); ``` -* `SIGUSR1` is reserved by Node.js to start the [debugger][]. It's possible to +* `'SIGUSR1'` is reserved by Node.js to start the [debugger][]. It's possible to install a listener but doing so might interfere with the debugger. -* `SIGTERM` and `SIGINT` have default handlers on non-Windows platforms that +* `'SIGTERM'` and `'SIGINT'` have default handlers on non-Windows platforms that reset the terminal mode before exiting with code `128 + signal number`. If one of these signals has a listener installed, its default behavior will be removed (Node.js will no longer exit). -* `SIGPIPE` is ignored by default. It can have a listener installed. -* `SIGHUP` is generated on Windows when the console window is closed, and on +* `'SIGPIPE'` is ignored by default. It can have a listener installed. +* `'SIGHUP'` is generated on Windows when the console window is closed, and on other platforms under various similar conditions, see signal(7). It can have a listener installed, however Node.js will be unconditionally terminated by Windows about 10 seconds later. On non-Windows platforms, the default behavior of `SIGHUP` is to terminate Node.js, but once a listener has been installed its default behavior will be removed. -* `SIGTERM` is not supported on Windows, it can be listened on. -* `SIGINT` from the terminal is supported on all platforms, and can usually be +* `'SIGTERM'` is not supported on Windows, it can be listened on. +* `'SIGINT'` from the terminal is supported on all platforms, and can usually be generated with `<Ctrl>+C` (though this may be configurable). It is not generated when terminal raw mode is enabled. -* `SIGBREAK` is delivered on Windows when `<Ctrl>+<Break>` is pressed, on +* `'SIGBREAK'` is delivered on Windows when `<Ctrl>+<Break>` is pressed, on non-Windows platforms it can be listened on, but there is no way to send or generate it. -* `SIGWINCH` is delivered when the console has been resized. On Windows, this +* `'SIGWINCH'` is delivered when the console has been resized. On Windows, this will only happen on write to the console when the cursor is being moved, or when a readable tty is used in raw mode. -* `SIGKILL` cannot have a listener installed, it will unconditionally terminate - Node.js on all platforms. -* `SIGSTOP` cannot have a listener installed. -* `SIGBUS`, `SIGFPE`, `SIGSEGV` and `SIGILL`, when not raised artificially - using kill(2), inherently leave the process in a state from which it is not - safe to attempt to call JS listeners. Doing so might lead to the process - hanging in an endless loop, since listeners attached using `process.on()` are - called asynchronously and therefore unable to correct the underlying problem. +* `'SIGKILL'` cannot have a listener installed, it will unconditionally + terminate Node.js on all platforms. +* `'SIGSTOP'` cannot have a listener installed. +* `'SIGBUS'`, `'SIGFPE'`, `'SIGSEGV'` and `'SIGILL'`, when not raised + artificially using kill(2), inherently leave the process in a state from + which it is not safe to attempt to call JS listeners. Doing so might lead to + the process hanging in an endless loop, since listeners attached using + `process.on()` are called asynchronously and therefore unable to correct the + underlying problem. Windows does not support sending signals, but Node.js offers some emulation with [`process.kill()`][], and [`subprocess.kill()`][]. Sending signal `0` can @@ -709,7 +710,7 @@ added: v8.0.0 The `process.emitWarning()` method can be used to emit custom or application specific process warnings. These can be listened for by adding a handler to the -[`process.on('warning')`][process_warning] event. +[`'warning'`][process_warning] event. ```js // Emit a warning with a code and additional detail. @@ -724,7 +725,7 @@ process.emitWarning('Something happened!', { In this example, an `Error` object is generated internally by `process.emitWarning()` and passed through to the -[`process.on('warning')`][process_warning] event. +[`'warning'`][process_warning] handler. ```js process.on('warning', (warning) => { @@ -753,7 +754,7 @@ added: v6.0.0 The `process.emitWarning()` method can be used to emit custom or application specific process warnings. These can be listened for by adding a handler to the -[`process.on('warning')`][process_warning] event. +[`'warning'`][process_warning] event. ```js // Emit a warning using a string. @@ -773,8 +774,8 @@ process.emitWarning('Something happened!', 'CustomWarning', 'WARN001'); ``` In each of the previous examples, an `Error` object is generated internally by -`process.emitWarning()` and passed through to the -[`process.on('warning')`][process_warning] event. +`process.emitWarning()` and passed through to the [`'warning'`][process_warning] +handler. ```js process.on('warning', (warning) => { @@ -786,7 +787,7 @@ process.on('warning', (warning) => { ``` If `warning` is passed as an `Error` object, it will be passed through to the -`process.on('warning')` event handler unmodified (and the optional `type`, +`'warning'` event handler unmodified (and the optional `type`, `code` and `ctor` arguments will be ignored): ```js @@ -807,7 +808,7 @@ Note that while process warnings use `Error` objects, the process warning mechanism is **not** a replacement for normal error handling mechanisms. The following additional handling is implemented if the warning `type` is -`DeprecationWarning`: +`'DeprecationWarning'`: * If the `--throw-deprecation` command-line flag is used, the deprecation warning is thrown as an exception rather than being emitted as an event. @@ -1416,8 +1417,8 @@ added: v0.8.0 The `process.noDeprecation` property indicates whether the `--no-deprecation` flag is set on the current Node.js process. See the documentation for -the [`warning` event][process_warning] and the -[`emitWarning` method][process_emit_warning] for more information about this +the [`'warning'` event][process_warning] and the +[`emitWarning()` method][process_emit_warning] for more information about this flag's behavior. ## process.pid @@ -1680,7 +1681,7 @@ The `process.setUncaughtExceptionCapture` function sets a function that will be invoked when an uncaught exception occurs, which will receive the exception value itself as its first argument. -If such a function is set, the [`process.on('uncaughtException')`][] event will +If such a function is set, the [`'uncaughtException'`][] event will not be emitted. If `--abort-on-uncaught-exception` was passed from the command line or set through [`v8.setFlagsFromString()`][], the process will not abort. @@ -1812,8 +1813,8 @@ added: v0.9.12 The `process.throwDeprecation` property indicates whether the `--throw-deprecation` flag is set on the current Node.js process. See the -documentation for the [`warning` event][process_warning] and the -[`emitWarning` method][process_emit_warning] for more information about this +documentation for the [`'warning'` event][process_warning] and the +[`emitWarning()` method][process_emit_warning] for more information about this flag's behavior. ## process.title @@ -1845,8 +1846,8 @@ added: v0.8.0 The `process.traceDeprecation` property indicates whether the `--trace-deprecation` flag is set on the current Node.js process. See the -documentation for the [`warning` event][process_warning] and the -[`emitWarning` method][process_emit_warning] for more information about this +documentation for the [`'warning'` event][process_warning] and the +[`emitWarning()` method][process_emit_warning] for more information about this flag's behavior. ## process.umask([mask]) @@ -2010,7 +2011,6 @@ cases: [`process.exit()`]: #process_process_exit_code [`process.exitCode`]: #process_process_exitcode [`process.kill()`]: #process_process_kill_pid_signal -[`process.on('uncaughtException')`]: process.html#process_event_uncaughtexception [`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn [`promise.catch()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch [`require()`]: globals.html#globals_require diff --git a/doc/api/readline.md b/doc/api/readline.md index 94151dfa62abc2..c1e50ef7eee350 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -56,7 +56,7 @@ The `'close'` event is emitted when one of the following occur: * The `input` stream receives its `'end'` event; * The `input` stream receives `<ctrl>-D` to signal end-of-transmission (EOT); * The `input` stream receives `<ctrl>-C` to signal `SIGINT` and there is no - `SIGINT` event listener registered on the `readline.Interface` instance. + `'SIGINT'` event listener registered on the `readline.Interface` instance. The listener function is called without passing any arguments. @@ -89,8 +89,8 @@ added: v0.7.5 The `'pause'` event is emitted when one of the following occur: * The `input` stream is paused. -* The `input` stream is not paused and receives the `SIGCONT` event. (See - events [`SIGTSTP`][] and [`SIGCONT`][]) +* The `input` stream is not paused and receives the `'SIGCONT'` event. (See + events [`'SIGTSTP'`][] and [`'SIGCONT'`][]) The listener function is called without passing any arguments. @@ -164,11 +164,11 @@ added: v0.7.5 --> The `'SIGTSTP'` event is emitted when the `input` stream receives a `<ctrl>-Z` -input, typically known as `SIGTSTP`. If there are no `SIGTSTP` event listeners +input, typically known as `SIGTSTP`. If there are no `'SIGTSTP'` event listeners registered when the `input` stream receives a `SIGTSTP`, the Node.js process will be sent to the background. -When the program is resumed using fg(1p), the `'pause'` and `SIGCONT` events +When the program is resumed using fg(1p), the `'pause'` and `'SIGCONT'` events will be emitted. These can be used to resume the `input` stream. The `'pause'` and `'SIGCONT'` events will not be emitted if the `input` was @@ -529,8 +529,8 @@ rl.on('line', (line) => { }); ``` -[`SIGCONT`]: readline.html#readline_event_sigcont -[`SIGTSTP`]: readline.html#readline_event_sigtstp +[`'SIGCONT'`]: readline.html#readline_event_sigcont +[`'SIGTSTP'`]: readline.html#readline_event_sigtstp [`process.stdin`]: process.html#process_process_stdin [`process.stdout`]: process.html#process_process_stdout [Readable]: stream.html#stream_readable_streams diff --git a/doc/api/stream.md b/doc/api/stream.md index 32be29182ceaeb..14724e8311a45f 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -128,7 +128,7 @@ const server = http.createServer((req, res) => { body += chunk; }); - // the end event indicates that the entire body has been received + // the 'end' event indicates that the entire body has been received req.on('end', () => { try { const data = JSON.parse(body); @@ -361,11 +361,11 @@ added: v8.0.0 * Returns: {this} -Destroy the stream, and emit the passed `error` and a `close` event. +Destroy the stream, and emit the passed `'error'` and a `'close'` event. After this call, the writable stream has ended and subsequent calls -to `write` / `end` will give an `ERR_STREAM_DESTROYED` error. +to `write()` / `end()` will give an `ERR_STREAM_DESTROYED` error. Implementors should not override this method, -but instead implement [`writable._destroy`][writable-_destroy]. +but instead implement [`writable._destroy()`][writable-_destroy]. ##### writable.end([chunk][, encoding][, callback]) <!-- YAML @@ -763,11 +763,11 @@ changes: - version: REPLACEME pr-url: https://github.com/nodejs/node/pull/17979 description: > - 'readable' is always emitted in the next tick after - .push() is called + The `'readable'` is always emitted in the next tick after `.push()` + is called - version: REPLACEME pr-url: https://github.com/nodejs/node/pull/18994 - description: Using 'readable' requires calling .read(). + description: Using `'readable'` requires calling `.read()`. --> The `'readable'` event is emitted when there is data available to be read from @@ -830,11 +830,11 @@ added: v8.0.0 * `error` {Error} Error which will be passed as payload in `'error'` event * Returns: {this} -Destroy the stream, and emit `'error'` and `close`. After this call, the +Destroy the stream, and emit `'error'` and `'close'`. After this call, the readable stream will release any internal resources and subsequent calls -to `push` will be ignored. +to `push()` will be ignored. Implementors should not override this method, but instead implement -[`readable._destroy`][readable-_destroy]. +[`readable._destroy()`][readable-_destroy]. ##### readable.isPaused() <!-- YAML @@ -1016,7 +1016,8 @@ added: v0.9.4 changes: - version: REPLACEME pr-url: https://github.com/nodejs/node/pull/18994 - description: Resume has no effect if there is a 'readable' event listening + description: The `resume()` has no effect if there is a `'readable'` event + listening. --> * Returns: {this} @@ -1149,7 +1150,7 @@ function parseHeader(stream, callback) { const remaining = split.join('\n\n'); const buf = Buffer.from(remaining, 'utf8'); stream.removeListener('error', callback); - // remove the readable listener before unshifting + // remove the 'readable' listener before unshifting stream.removeListener('readable', onReadable); if (buf.length) stream.unshift(buf); @@ -1285,8 +1286,8 @@ added: v8.0.0 Destroy the stream, and emit `'error'`. After this call, the transform stream would release any internal resources. implementors should not override this method, but instead implement -[`readable._destroy`][readable-_destroy]. -The default implementation of `_destroy` for `Transform` also emit `'close'`. +[`readable._destroy()`][readable-_destroy]. +The default implementation of `_destroy()` for `Transform` also emit `'close'`. ## API for Stream Implementers @@ -1425,7 +1426,7 @@ changes: - version: REPLACEME pr-url: https://github.com/nodejs/node/pull/18438 description: > - Add `emitClose` option to specify if `close` is emitted on destroy + Add `emitClose` option to specify if `'close'` is emitted on destroy --> * `options` {Object} @@ -1440,7 +1441,7 @@ changes: it becomes possible to write JavaScript values other than string, `Buffer` or `Uint8Array` if supported by the stream implementation. **Default:** `false`. - * `emitClose` {boolean} Whether or not the stream should emit `close` + * `emitClose` {boolean} Whether or not the stream should emit `'close'` after it has been destroyed. **Default:** `true`. * `write` {Function} Implementation for the [`stream._write()`][stream-_write] method. @@ -1581,7 +1582,7 @@ by child classes, and if so, will be called by the internal Writable class methods only. This optional function will be called before the stream closes, delaying the -`finish` event until `callback` is called. This is useful to close resources +`'finish'` event until `callback` is called. This is useful to close resources or write buffered data before a stream ends. #### Errors While Writing @@ -2286,7 +2287,7 @@ For example, consider the following code: // WARNING! BROKEN! net.createServer((socket) => { - // we add an 'end' method, but never consume the data + // we add an 'end' listener, but never consume the data socket.on('end', () => { // It will never get here. socket.end('The message was received but was not processed.\n'); diff --git a/doc/api/timers.md b/doc/api/timers.md index b95c6396032b6f..9c455552b1454c 100644 --- a/doc/api/timers.md +++ b/doc/api/timers.md @@ -34,7 +34,7 @@ When called, requests that the Node.js event loop *not* exit so long as the `Immediate` is active. Calling `immediate.ref()` multiple times will have no effect. -By default, all `Immediate` objects are "ref'd", making it normally unnecessary +By default, all `Immediate` objects are "ref'ed", making it normally unnecessary to call `immediate.ref()` unless `immediate.unref()` had been called previously. Returns a reference to the `Immediate`. @@ -75,7 +75,7 @@ added: v0.9.1 When called, requests that the Node.js event loop *not* exit so long as the `Timeout` is active. Calling `timeout.ref()` multiple times will have no effect. -By default, all `Timeout` objects are "ref'd", making it normally unnecessary +By default, all `Timeout` objects are "ref'ed", making it normally unnecessary to call `timeout.ref()` unless `timeout.unref()` had been called previously. Returns a reference to the `Timeout`. diff --git a/doc/api/tls.md b/doc/api/tls.md index 1e20f916ab0f06..0f9e46f2474d57 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -261,7 +261,7 @@ The typical flow of an OCSP Request is as follows: listener if registered. 3. Server extracts the OCSP URL from either the `certificate` or `issuer` and performs an [OCSP request] to the CA. -4. Server receives `OCSPResponse` from the CA and sends it back to the client +4. Server receives `'OCSPResponse'` from the CA and sends it back to the client via the `callback` argument 5. Client validates the response and either destroys the socket or performs a handshake. @@ -1307,7 +1307,8 @@ deprecated: v0.11.3 The `'secure'` event is emitted by the `SecurePair` object once a secure connection has been established. -As with checking for the server [`secureConnection`](#tls_event_secureconnection) +As with checking for the server +[`'secureConnection'`](#tls_event_secureconnection) event, `pair.cleartext.authorized` should be inspected to confirm whether the certificate used is properly authorized. diff --git a/doc/api/util.md b/doc/api/util.md index 0b2de54ff2bd01..effe5074d2be89 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -144,7 +144,7 @@ exports.obsoleteFunction = util.deprecate(() => { ``` When called, `util.deprecate()` will return a function that will emit a -`DeprecationWarning` using the `process.on('warning')` event. The warning will +`DeprecationWarning` using the [`'warning'`][] event. The warning will be emitted and printed to `stderr` the first time the returned function is called. After the warning is emitted, the wrapped function is called without emitting a warning. @@ -2030,6 +2030,7 @@ deprecated: v0.11.3 Deprecated predecessor of `console.log`. [`'uncaughtException'`]: process.html#process_event_uncaughtexception +[`'warning'`]: process.html#process_event_warning [`Array.isArray()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray [`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer [`ArrayBuffer.isView()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/isView diff --git a/doc/api/zlib.md b/doc/api/zlib.md index f9967773e94fea..053cd2893aabe7 100644 --- a/doc/api/zlib.md +++ b/doc/api/zlib.md @@ -338,13 +338,13 @@ changes: - version: v6.0.0 pr-url: https://github.com/nodejs/node/pull/5883 description: Trailing garbage at the end of the input stream will now - result in an `error` event. + result in an `'error'` event. - version: v5.9.0 pr-url: https://github.com/nodejs/node/pull/5120 description: Multiple concatenated gzip file members are supported now. - version: v5.0.0 pr-url: https://github.com/nodejs/node/pull/2595 - description: A truncated input stream will now result in an `error` event. + description: A truncated input stream will now result in an `'error'` event. --> Decompress a gzip stream. @@ -362,7 +362,7 @@ added: v0.5.8 changes: - version: v5.0.0 pr-url: https://github.com/nodejs/node/pull/2595 - description: A truncated input stream will now result in an `error` event. + description: A truncated input stream will now result in an `'error'` event. --> Decompress a deflate stream. @@ -376,7 +376,7 @@ changes: description: Custom dictionaries are now supported by `InflateRaw`. - version: v5.0.0 pr-url: https://github.com/nodejs/node/pull/2595 - description: A truncated input stream will now result in an `error` event. + description: A truncated input stream will now result in an `'error'` event. --> Decompress a raw deflate stream.