Skip to content

Commit

Permalink
doc: edit for concision
Browse files Browse the repository at this point in the history
This removes some wordy phrases (notably "it is important to note
that").

PR-URL: #17891
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
  • Loading branch information
Trott authored and MylesBorins committed Jan 9, 2018
1 parent 3fd6581 commit 445c911
Show file tree
Hide file tree
Showing 6 changed files with 25 additions and 35 deletions.
11 changes: 5 additions & 6 deletions doc/api/async_hooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down Expand Up @@ -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.

Expand Down
9 changes: 4 additions & 5 deletions doc/api/errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand Down
19 changes: 7 additions & 12 deletions doc/api/process.md
Original file line number Diff line number Diff line change
Expand Up @@ -374,16 +374,11 @@ process.on('SIGINT', handle);
process.on('SIGTERM', handle);
```

*Note*: An easy way to send the `SIGINT` signal is with `<Ctrl>-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
Expand All @@ -394,7 +389,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 `<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
non-Windows platforms it can be listened on, but there is no way to send or
Expand Down Expand Up @@ -989,10 +984,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
Expand Down
5 changes: 2 additions & 3 deletions doc/api/repl.md
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand Down
11 changes: 5 additions & 6 deletions doc/api/stream.md
Original file line number Diff line number Diff line change
Expand Up @@ -1426,12 +1426,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
Expand Down
5 changes: 2 additions & 3 deletions doc/api/vm.md
Original file line number Diff line number Diff line change
Expand Up @@ -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])
<!-- YAML
Expand Down

0 comments on commit 445c911

Please sign in to comment.