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 <[email protected]>
Reviewed-By: Trivikram Kamat <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Gireesh Punathil <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: James M Snell <[email protected]>

Author: Trott

doc/api/addons.md

@@ -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

doc/api/child_process.md

@@ -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()`][].

doc/api/crypto.md

@@ -1672,8 +1672,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
@@ -1766,8 +1766,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

doc/api/dgram.md

@@ -433,7 +433,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.
 

doc/api/events.md

@@ -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:
 

doc/api/n-api.md

@@ -808,11 +808,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,
@@ -4318,8 +4318,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.
@@ -4922,9 +4921,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
@@ -4969,13 +4968,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()`.
 

doc/api/stream.md

@@ -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
@@ -1654,11 +1654,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
@@ -2604,8 +2604,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');

doc/releases.md

@@ -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!**
 

lib/_tls_common.js

@@ -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.

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

@@ -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,

test/parallel/test-url-parse-format.js

@@ -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=\[email protected]\x27': {
     protocol: 'javascript:',
     slashes: null,