FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: remove "it is important to" phrasing · nodejs/node@621eaf9 · GitHub

/ node Public

Commit 621eaf9

Browse files
Trott
authored and
targos
committed
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>
1 parent d78e317 commit 621eaf9

11 files changed

Lines changed: 45 additions & 50 deletions

File tree

‎doc/api/addons.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -364,13 +364,12 @@ and load it instead.
364364
## Native Abstractions for Node.js
365365

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

375374
The [Native Abstractions for Node.js][] (or `nan`) provide a set of tools that
376375
Addon developers are recommended to use to keep compatibility between past and

‎doc/api/child_process.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -361,7 +361,7 @@ returned [`ChildProcess`][] will have an additional communication channel
361361
built-in that allows messages to be passed back and forth between the parent and
362362
child. See [`subprocess.send()`][] for details.
363363

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

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

961961
See also [`subprocess.kill()`][] and [`subprocess.send()`][].

‎doc/api/crypto.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1707,8 +1707,8 @@ Initialization vectors should be unpredictable and unique; ideally, they will be
17071707
cryptographically random. They do not have to be secret: IVs are typically just
17081708
added to ciphertext messages unencrypted. It may sound contradictory that
17091709
something has to be unpredictable and unique, but does not have to be secret;
1710-
it is important to remember that an attacker must not be able to predict ahead
1711-
of time what a given IV will be.
1710+
remember that an attacker must not be able to predict ahead of time what a
1711+
given IV will be.
17121712

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

18071807
### crypto.createDiffieHellman(prime\[, primeEncoding\]\[, generator\]\[, generatorEncoding\])
18081808
<!-- YAML

‎doc/api/dgram.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -466,7 +466,7 @@ client.send([buf1, buf2], 41234, (err) => {
466466
```
467467

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

‎doc/api/events.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ myEmitter.emit('event');
4343
## Passing arguments and `this` to listeners
4444

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

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

‎doc/api/n-api.md‎

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -810,11 +810,11 @@ When an exception is pending one of two approaches can be employed.
810810

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

819819
The second approach is to try to handle the exception. There will be cases
820820
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.
43444344
Addon modules often need to leverage async helpers from libuv as part of their
43454345
implementation. This allows them to schedule work to be executed asynchronously
43464346
so that their methods can return in advance of the work being completed. This
4347-
is important in order to allow them to avoid blocking overall execution
4348-
of the Node.js application.
4347+
allows them to avoid blocking overall execution of the Node.js application.
43494348

43504349
N-API provides an ABI-stable interface for these
43514350
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
49484947
provided. This callback will be invoked on the main thread when the thread-safe
49494948
function is about to be destroyed. It receives the context and the finalize data
49504949
given during construction, and provides an opportunity for cleaning up after the
4951-
threads e.g. by calling `uv_thread_join()`. **It is important that, aside from
4952-
the main loop thread, there be no threads left using the thread-safe function
4953-
after the finalize callback completes.**
4950+
threads e.g. by calling `uv_thread_join()`. **Aside from the main loop thread,
4951+
no threads should be using the thread-safe function after the finalize callback
4952+
completes.**
49544953

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

‎doc/api/stream.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ maintaining an appropriate and efficient flow of data. For example,
100100
[`net.Socket`][] instances are [`Duplex`][] streams whose `Readable` side allows
101101
consumption of data received *from* the socket and whose `Writable` side allows
102102
writing data *to* the socket. Because data may be written to the socket at a
103-
faster or slower rate than data is received, it is important for each side to
103+
faster or slower rate than data is received, each side should
104104
operate (and buffer) independently of the other.
105105

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

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

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

26102610
#### Piping to Writable Streams from Async Iterators
26112611

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

26152615
```js
26162616
const { once } = require('events');

‎doc/releases.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -540,7 +540,7 @@ formatting passes the lint rules on `master`.
540540

541541
### 13. Promote and Sign the Release Builds
542542

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

‎lib/_tls_common.js‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -100,8 +100,7 @@ exports.createSecureContext = function createSecureContext(options) {
100100
var i;
101101
var val;
102102

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

135-
// NOTE: It is important to set the key after the cert.
134+
// Set the key after the cert.
136135
// `ssl_set_pkey` returns `0` when the key does not match the cert, but
137136
// `ssl_set_cert` returns `1` and nullifies the key in the SSL structure
138137
// which leads to the crash later on.

‎test/js-native-api/8_passing_wrapped/myobject.cc‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -51,10 +51,9 @@ napi_value MyObject::New(napi_env env, napi_callback_info info) {
5151

5252
obj->env_ = env;
5353

54-
// It is important that the below call to napi_wrap() be such that we request
55-
// a reference to the wrapped object via the out-parameter, because this
56-
// ensures that we test the code path that deals with a reference that is
57-
// destroyed from its own finalizer.
54+
// The below call to napi_wrap() must request a reference to the wrapped
55+
// object via the out-parameter, because this ensures that we test the code
56+
// path that deals with a reference that is destroyed from its own finalizer.
5857
NAPI_CALL(env, napi_wrap(env,
5958
_this,
6059
obj,

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL