Skip to content
Permalink
Browse files

doc: remove "it is important to" phrasing

Instead of telling someone "It is important to do X", just tell them to
"Do X."

PR-URL: #30108
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
  • Loading branch information...
Trott committed Oct 24, 2019
1 parent ab78d4d commit 72346bd8d43477273419049ab68a5c6611480a92
@@ -364,13 +364,12 @@ and load it instead.
## Native Abstractions for Node.js

Each of the examples illustrated in this document make direct use of the
Node.js and V8 APIs for implementing Addons. It is important to understand
that the V8 API can, and has, changed dramatically from one V8 release to the
next (and one major Node.js release to the next). With each change, Addons may
need to be updated and recompiled in order to continue functioning. The Node.js
release schedule is designed to minimize the frequency and impact of such
changes but there is little that Node.js can do currently to ensure stability
of the V8 APIs.
Node.js and V8 APIs for implementing Addons. The V8 API can, and has, changed
dramatically from one V8 release to the next (and one major Node.js release to
the next). With each change, Addons may need to be updated and recompiled in
order to continue functioning. The Node.js release schedule is designed to
minimize the frequency and impact of such changes but there is little that
Node.js can do currently to ensure stability of the V8 APIs.

The [Native Abstractions for Node.js][] (or `nan`) provide a set of tools that
Addon developers are recommended to use to keep compatibility between past and
@@ -361,7 +361,7 @@ returned [`ChildProcess`][] will have an additional communication channel
built-in that allows messages to be passed back and forth between the parent and
child. See [`subprocess.send()`][] for details.

It is important to keep in mind that spawned Node.js child processes are
Keep in mind that spawned Node.js child processes are
independent of the parent with exception of the IPC communication channel
that is established between the two. Each process has its own memory, with
their own V8 instances. Because of the additional resource allocations
@@ -955,7 +955,7 @@ The `'error'` event is emitted whenever:
3. Sending a message to the child process failed.

The `'exit'` event may or may not fire after an error has occurred. When
listening to both the `'exit'` and `'error'` events, it is important to guard
listening to both the `'exit'` and `'error'` events, guard
against accidentally invoking handler functions multiple times.

See also [`subprocess.kill()`][] and [`subprocess.send()`][].
@@ -1707,8 +1707,8 @@ Initialization vectors should be unpredictable and unique; ideally, they will be
cryptographically random. They do not have to be secret: IVs are typically just
added to ciphertext messages unencrypted. It may sound contradictory that
something has to be unpredictable and unique, but does not have to be secret;
it is important to remember that an attacker must not be able to predict ahead
of time what a given IV will be.
remember that an attacker must not be able to predict ahead of time what a
given IV will be.

### crypto.createDecipher(algorithm, password\[, options\])
<!-- YAML
@@ -1801,8 +1801,8 @@ Initialization vectors should be unpredictable and unique; ideally, they will be
cryptographically random. They do not have to be secret: IVs are typically just
added to ciphertext messages unencrypted. It may sound contradictory that
something has to be unpredictable and unique, but does not have to be secret;
it is important to remember that an attacker must not be able to predict ahead
of time what a given IV will be.
remember that an attacker must not be able to predict ahead of time what a given
IV will be.

### crypto.createDiffieHellman(prime\[, primeEncoding\]\[, generator\]\[, generatorEncoding\])
<!-- YAML
@@ -466,7 +466,7 @@ client.send([buf1, buf2], 41234, (err) => {
```

Sending multiple buffers might be faster or slower depending on the
application and operating system. It is important to run benchmarks to
application and operating system. Run benchmarks to
determine the optimal strategy on a case-by-case basis. Generally speaking,
however, sending multiple buffers is faster.

@@ -43,7 +43,7 @@ myEmitter.emit('event');
## Passing arguments and `this` to listeners

The `eventEmitter.emit()` method allows an arbitrary set of arguments to be
passed to the listener functions. It is important to keep in mind that when
passed to the listener functions. Keep in mind that when
an ordinary listener function is called, the standard `this` keyword
is intentionally set to reference the `EventEmitter` instance to which the
listener is attached.
@@ -77,8 +77,8 @@ myEmitter.emit('event', 'a', 'b');
## Asynchronous vs. Synchronous

The `EventEmitter` calls all listeners synchronously in the order in which
they were registered. This is important to ensure the proper sequencing of
events and to avoid race conditions or logic errors. When appropriate,
they were registered. This ensures the proper sequencing of
events and helps avoid race conditions and logic errors. When appropriate,
listener functions can switch to an asynchronous mode of operation using
the `setImmediate()` or `process.nextTick()` methods:

@@ -810,11 +810,11 @@ When an exception is pending one of two approaches can be employed.

The first approach is to do any appropriate cleanup and then return so that
execution will return to JavaScript. As part of the transition back to
JavaScript the exception will be thrown at the point in the JavaScript
JavaScript, the exception will be thrown at the point in the JavaScript
code where the native method was invoked. The behavior of most N-API calls
is unspecified while an exception is pending, and many will simply return
`napi_pending_exception`, so it is important to do as little as possible
and then return to JavaScript where the exception can be handled.
`napi_pending_exception`, so do as little as possible and then return to
JavaScript where the exception can be handled.

The second approach is to try to handle the exception. There will be cases
where the native code can catch the exception, take the appropriate action,
@@ -4344,8 +4344,7 @@ required in order to enable correct disposal of the reference.
Addon modules often need to leverage async helpers from libuv as part of their
implementation. This allows them to schedule work to be executed asynchronously
so that their methods can return in advance of the work being completed. This
is important in order to allow them to avoid blocking overall execution
of the Node.js application.
allows them to avoid blocking overall execution of the Node.js application.

N-API provides an ABI-stable interface for these
supporting functions which covers the most common asynchronous use cases.
@@ -4948,9 +4947,9 @@ Upon creation of a `napi_threadsafe_function` a `napi_finalize` callback can be
provided. This callback will be invoked on the main thread when the thread-safe
function is about to be destroyed. It receives the context and the finalize data
given during construction, and provides an opportunity for cleaning up after the
threads e.g. by calling `uv_thread_join()`. **It is important that, aside from
the main loop thread, there be no threads left using the thread-safe function
after the finalize callback completes.**
threads e.g. by calling `uv_thread_join()`. **Aside from the main loop thread,
no threads should be using the thread-safe function after the finalize callback
completes.**

The `context` given during the call to `napi_create_threadsafe_function()` can
be retrieved from any thread with a call to
@@ -4995,13 +4994,13 @@ existing thread will stop making use of the thread-safe function.
the object has called `napi_release_threadsafe_function()` or has received a
return status of `napi_closing` in response to a call to
`napi_call_threadsafe_function`. The queue is emptied before the
`napi_threadsafe_function` is destroyed. It is important that
`napi_release_threadsafe_function()` be the last API call made in conjunction
with a given `napi_threadsafe_function`, because after the call completes, there
is no guarantee that the `napi_threadsafe_function` is still allocated. For the
same reason it is also important that no more use be made of a thread-safe
function after receiving a return value of `napi_closing` in response to a call
to `napi_call_threadsafe_function`. Data associated with the
`napi_threadsafe_function` is destroyed. `napi_release_threadsafe_function()`
should be the last API call made in conjunction with a given
`napi_threadsafe_function`, because after the call completes, there is no
guarantee that the `napi_threadsafe_function` is still allocated. For the same
reason, do not make use of a thread-safe function
after receiving a return value of `napi_closing` in response to a call to
`napi_call_threadsafe_function`. Data associated with the
`napi_threadsafe_function` can be freed in its `napi_finalize` callback which
was passed to `napi_create_threadsafe_function()`.

@@ -100,7 +100,7 @@ maintaining an appropriate and efficient flow of data. For example,
[`net.Socket`][] instances are [`Duplex`][] streams whose `Readable` side allows
consumption of data received *from* the socket and whose `Writable` side allows
writing data *to* the socket. Because data may be written to the socket at a
faster or slower rate than data is received, it is important for each side to
faster or slower rate than data is received, each side should
operate (and buffer) independently of the other.

## API for Stream Consumers
@@ -1658,11 +1658,11 @@ class MyWritable extends Writable {
}
```

When extending streams, it is important to keep in mind what options the user
When extending streams, keep in mind what options the user
can and should provide before forwarding these to the base constructor. For
example, if the implementation makes assumptions in regard to e.g. the
`autoDestroy` and `emitClose` options, it becomes important to not allow the
user to override these. It is therefore recommended to be explicit about what
example, if the implementation makes assumptions in regard to the
`autoDestroy` and `emitClose` options, do not allow the
user to override these. Be explicit about what
options are forwarded instead of implicitly forwarding all options.

The new stream class must then implement one or more specific methods, depending
@@ -2609,8 +2609,8 @@ readable.on('data', (chunk) => {

#### Piping to Writable Streams from Async Iterators

In the scenario of writing to a writable stream from an async iterator,
it is important to ensure the correct handling of backpressure and errors.
In the scenario of writing to a writable stream from an async iterator, ensure
the correct handling of backpressure and errors.

```js
const { once } = require('events');
@@ -540,7 +540,7 @@ formatting passes the lint rules on `master`.

### 13. Promote and Sign the Release Builds

**It is important that the same individual who signed the release tag be the one
**The same individual who signed the release tag must be the one
to promote the builds as the SHASUMS256.txt file needs to be signed with the
same GPG key!**

@@ -100,8 +100,7 @@ exports.createSecureContext = function createSecureContext(options) {
var i;
var val;

// NOTE: It's important to add CA before the cert to be able to load
// cert's issuer in C++ code.
// Add CA before the cert to be able to load cert's issuer in C++ code.
const { ca } = options;
if (ca) {
if (Array.isArray(ca)) {
@@ -132,7 +131,7 @@ exports.createSecureContext = function createSecureContext(options) {
}
}

// NOTE: It is important to set the key after the cert.
// Set the key after the cert.
// `ssl_set_pkey` returns `0` when the key does not match the cert, but
// `ssl_set_cert` returns `1` and nullifies the key in the SSL structure
// which leads to the crash later on.
@@ -51,10 +51,9 @@ napi_value MyObject::New(napi_env env, napi_callback_info info) {

obj->env_ = env;

// It is important that the below call to napi_wrap() be such that we request
// a reference to the wrapped object via the out-parameter, because this
// ensures that we test the code path that deals with a reference that is
// destroyed from its own finalizer.
// The below call to napi_wrap() must request a reference to the wrapped
// object via the out-parameter, because this ensures that we test the code
// path that deals with a reference that is destroyed from its own finalizer.
NAPI_CALL(env, napi_wrap(env,
_this,
obj,
@@ -892,9 +892,8 @@ const parseTests = {
href: 'https:///*'
},

// The following two URLs are the same, but they differ for
// a capital A: it is important that we verify that the protocol
// is checked in a case-insensitive manner.
// The following two URLs are the same, but they differ for a capital A.
// Verify that the protocol is checked in a case-insensitive manner.
'javascript:alert(1);a=\x27@white-listed.com\x27': {
protocol: 'javascript:',
slashes: null,

0 comments on commit 72346bd

Please sign in to comment.
You can’t perform that action at this time.