From 532e85a7498837c058067ddafb5325fc47966f86 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 27 Dec 2017 19:21:06 -0800 Subject: [PATCH] doc: edit for concision This removes some wordy phrases (notably "it is important to note that"). PR-URL: https://github.com/nodejs/node/pull/17891 Reviewed-By: Gibson Fahnestock Reviewed-By: Colin Ihrig Reviewed-By: Joyee Cheung --- doc/api/async_hooks.md | 11 +++++------ doc/api/errors.md | 9 ++++----- doc/api/process.md | 19 +++++++------------ doc/api/repl.md | 5 ++--- doc/api/stream.md | 11 +++++------ doc/api/vm.md | 5 ++--- 6 files changed, 25 insertions(+), 35 deletions(-) diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 7d07622eda7403..e8cb9344c4c123 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -484,9 +484,8 @@ fs.open(path, 'r', (err, fd) => { }); ``` -It is important to note that the ID returned fom `executionAsyncId()` is related -to execution timing, not causality (which is covered by `triggerAsyncId()`). For -example: +The ID returned fom `executionAsyncId()` is related to execution timing, not +causality (which is covered by `triggerAsyncId()`). For example: ```js const server = net.createServer(function onConnection(conn) { @@ -538,9 +537,9 @@ own resources. The `init` hook will trigger when an `AsyncResource` is instantiated. -*Note*: It is important that `before`/`after` calls are unwound -in the same order they are called. Otherwise an unrecoverable exception -will occur and the process will abort. +*Note*: `before` and `after` calls must be unwound in the same order that they +are called. Otherwise, an unrecoverable exception will occur and the process +will abort. The following is an overview of the `AsyncResource` API. diff --git a/doc/api/errors.md b/doc/api/errors.md index 4b44cdbcd3a4d3..b43a3395bff615 100755 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -312,11 +312,10 @@ location information will be displayed for that frame. Otherwise, the determined function name will be displayed with location information appended in parentheses. -It is important to note that frames are **only** generated for JavaScript -functions. If, for example, execution synchronously passes through a C++ addon -function called `cheetahify`, which itself calls a JavaScript function, the -frame representing the `cheetahify` call will **not** be present in the stack -traces: +Frames are only generated for JavaScript functions. If, for example, execution +synchronously passes through a C++ addon function called `cheetahify` which +itself calls a JavaScript function, the frame representing the `cheetahify` call +will not be present in the stack traces: ```js const cheetahify = require('./native-binding.node'); diff --git a/doc/api/process.md b/doc/api/process.md index f01417cda4a531..6e90fa31a5955b 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -363,16 +363,11 @@ process.on('SIGINT', () => { }); ``` -*Note*: An easy way to send the `SIGINT` signal is with `-C` in most -terminal programs. - -It is important to take note of the following: - * `SIGUSR1` is reserved by Node.js to start the [debugger][]. It's possible to install a listener but doing so will _not_ stop the debugger from starting. * `SIGTERM` and `SIGINT` have default handlers on non-Windows platforms that - resets the terminal mode before exiting with code `128 + signal number`. If - one of these signals has a listener installed, its default behavior will be + 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 @@ -383,7 +378,7 @@ It is important to take note of the following: 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 - generated with `CTRL+C` (though this may be configurable). It is not generated + generated with `+C` (though this may be configurable). It is not generated when terminal raw mode is enabled. * `SIGBREAK` is delivered on Windows when `+` is pressed, on non-Windows platforms it can be listened on, but there is no way to send or @@ -934,10 +929,10 @@ process.exit(1); The shell that executed Node.js should see the exit code as `1`. -It is important to note that calling `process.exit()` will force the process to -exit as quickly as possible *even if there are still asynchronous operations -pending* that have not yet completed fully, *including* I/O operations to -`process.stdout` and `process.stderr`. +Calling `process.exit()` will force the process to exit as quickly as possible +even if there are still asynchronous operations pending that have not yet +completed fully, including I/O operations to `process.stdout` and +`process.stderr`. In most situations, it is not actually necessary to call `process.exit()` explicitly. The Node.js process will exit on its own *if there is no additional diff --git a/doc/api/repl.md b/doc/api/repl.md index 167b9a1d9b9abf..0ff4ee099cb428 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -114,9 +114,8 @@ $ node repl_test.js 'message' ``` -It is important to note that context properties are *not* read-only by default. -To specify read-only globals, context properties must be defined using -`Object.defineProperty()`: +Context properties are not read-only by default. To specify read-only globals, +context properties must be defined using `Object.defineProperty()`: ```js const repl = require('repl'); diff --git a/doc/api/stream.md b/doc/api/stream.md index dec38202221b70..6c024124928e96 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -1409,12 +1409,11 @@ successfully or failed with an error. The first argument passed to the `callback` must be the `Error` object if the call failed or `null` if the write succeeded. -It is important to note that all calls to `writable.write()` that occur between -the time `writable._write()` is called and the `callback` is called will cause -the written data to be buffered. Once the `callback` is invoked, the stream will -emit a [`'drain'`][] event. If a stream implementation is capable of processing -multiple chunks of data at once, the `writable._writev()` method should be -implemented. +All calls to `writable.write()` that occur between the time `writable._write()` +is called and the `callback` is called will cause the written data to be +buffered. Once the `callback` is invoked, the stream will emit a [`'drain'`][] +event. If a stream implementation is capable of processing multiple chunks of +data at once, the `writable._writev()` method should be implemented. If the `decodeStrings` property is set in the constructor options, then `chunk` may be a string rather than a Buffer, and `encoding` will diff --git a/doc/api/vm.md b/doc/api/vm.md index 9918a2bd568a31..41101a5e5cf76f 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -87,9 +87,8 @@ changes: depending on whether code cache data is produced successfully. Creating a new `vm.Script` object compiles `code` but does not run it. The -compiled `vm.Script` can be run later multiple times. It is important to note -that the `code` is not bound to any global object; rather, it is bound before -each run, just for that run. +compiled `vm.Script` can be run later multiple times. The `code` is not bound to +any global object; rather, it is bound before each run, just for that run. ### script.runInContext(contextifiedSandbox[, options])