Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 2ac76e3

Browse filesBrowse files
Trotttargos
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 ec99287 commit 2ac76e3
Copy full SHA for 2ac76e3

File tree

Expand file treeCollapse file tree

11 files changed

+45
-50
lines changed
Open diff view settings
Filter options
Expand file treeCollapse file tree

11 files changed

+45
-50
lines changed
Open diff view settings
Collapse file

‎doc/api/addons.md‎

Copy file name to clipboardExpand all lines: doc/api/addons.md
+6-7Lines changed: 6 additions & 7 deletions
  • Display the source diff
  • Display the rich diff
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
Collapse file

‎doc/api/child_process.md‎

Copy file name to clipboardExpand all lines: doc/api/child_process.md
+2-2Lines changed: 2 additions & 2 deletions
  • Display the source diff
  • Display the rich diff
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()`][].
Collapse file

‎doc/api/crypto.md‎

Copy file name to clipboardExpand all lines: doc/api/crypto.md
+4-4Lines changed: 4 additions & 4 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -1672,8 +1672,8 @@ Initialization vectors should be unpredictable and unique; ideally, they will be
16721672
cryptographically random. They do not have to be secret: IVs are typically just
16731673
added to ciphertext messages unencrypted. It may sound contradictory that
16741674
something has to be unpredictable and unique, but does not have to be secret;
1675-
it is important to remember that an attacker must not be able to predict ahead
1676-
of time what a given IV will be.
1675+
remember that an attacker must not be able to predict ahead of time what a
1676+
given IV will be.
16771677

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

17721772
### crypto.createDiffieHellman(prime\[, primeEncoding\]\[, generator\]\[, generatorEncoding\])
17731773
<!-- YAML
Collapse file

‎doc/api/dgram.md‎

Copy file name to clipboardExpand all lines: doc/api/dgram.md
+1-1Lines changed: 1 addition & 1 deletion
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -433,7 +433,7 @@ client.send([buf1, buf2], 41234, (err) => {
433433
```
434434

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

Collapse file

‎doc/api/events.md‎

Copy file name to clipboardExpand all lines: doc/api/events.md
+3-3Lines changed: 3 additions & 3 deletions
  • Display the source diff
  • Display the rich diff
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

Collapse file

‎doc/api/n-api.md‎

Copy file name to clipboardExpand all lines: doc/api/n-api.md
+14-15Lines changed: 14 additions & 15 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -808,11 +808,11 @@ When an exception is pending one of two approaches can be employed.
808808

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

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

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

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

Collapse file

‎doc/api/stream.md‎

Copy file name to clipboardExpand all lines: doc/api/stream.md
+7-7Lines changed: 7 additions & 7 deletions
  • Display the source diff
  • Display the rich diff
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
@@ -1654,11 +1654,11 @@ class MyWritable extends Writable {
16541654
}
16551655
```
16561656

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

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

26052605
#### Piping to Writable Streams from Async Iterators
26062606

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

26102610
```js
26112611
const { once } = require('events');
Collapse file

‎doc/releases.md‎

Copy file name to clipboardExpand all lines: doc/releases.md
+1-1Lines changed: 1 addition & 1 deletion
  • Display the source diff
  • Display the rich diff
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

Collapse file

‎lib/_tls_common.js‎

Copy file name to clipboardExpand all lines: lib/_tls_common.js
+2-3Lines 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.
Collapse file

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

Copy file name to clipboardExpand all lines: test/js-native-api/8_passing_wrapped/myobject.cc
+3-4Lines 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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.