doc: make the style of notes consistent

Make the style of "Note:" paragraphs consistent and document the
guidelines in `doc/STYLE_GUIDE.md`.

Fixes: nodejs#13131

doc/STYLE_GUIDE.md

@@ -61,6 +61,10 @@
 * References to constructor instances should use camelCase.
 * References to methods should be used with parentheses: for example,
   `socket.end()` instead of `socket.end`.
+* To draw special attention to a note, adhere to the following guidelines:
+  * Make the "Note:" label bold, i.e. `**Note:**`.
+  * Use a capital letter after the "Note:" label.
+  * Preferably, make the note a new paragraph for better visual distinction.
 
 [plugin]: http://editorconfig.org/#download
 [Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma

doc/api/addons.md

@@ -113,13 +113,13 @@ specifically to compile Node.js Addons.
 }
 ```
 
-*Note: A version of the `node-gyp` utility is bundled and distributed with
+**Note:** A version of the `node-gyp` utility is bundled and distributed with
 Node.js as part of `npm`. This version is not made directly available for
 developers to use and is intended only to support the ability to use the
 `npm install` command to compile and install Addons. Developers who wish to
 use `node-gyp` directly can install it using the command
 `npm install -g node-gyp`. See the `node-gyp` [installation instructions][] for
-more information, including platform-specific requirements.*
+more information, including platform-specific requirements.
 
 Once the `binding.gyp` file has been created, use `node-gyp configure` to
 generate the appropriate project build files for the current platform. This

doc/api/buffer.md

@@ -193,11 +193,11 @@ The character encodings currently supported by Node.js include:
 
 * `'hex'` - Encode each byte as two hexadecimal characters.
 
-_Note_: Today's browsers follow the [WHATWG spec] which aliases both 'latin1' and
-ISO-8859-1 to win-1252. This means that while doing something like `http.get()`,
-if the returned charset is one of those listed in the WHATWG spec it's possible
-that the server actually returned win-1252-encoded data, and using `'latin1'`
-encoding may incorrectly decode the characters.
+**Note:** Today's browsers follow the [WHATWG spec] which aliases both 'latin1'
+and ISO-8859-1 to win-1252. This means that while doing something like
+`http.get()`, if the returned charset is one of those listed in the WHATWG spec
+it's possible that the server actually returned win-1252-encoded data, and
+using `'latin1'` encoding may incorrectly decode the characters.
 
 ## Buffers and TypedArray
 <!-- YAML
@@ -686,7 +686,7 @@ Returns the actual byte length of a string. This is not the same as
 [`String.prototype.length`] since that returns the number of *characters* in
 a string.
 
-*Note* that for `'base64'` and `'hex'`, this function assumes valid input. For
+**Note:** For `'base64'` and `'hex'`, this function assumes valid input. For
 strings that contain non-Base64/Hex-encoded data (e.g. whitespace), the return
 value might be greater than the length of a `Buffer` created from the string.
 
@@ -1868,8 +1868,8 @@ changes:
 Returns a new `Buffer` that references the same memory as the original, but
 offset and cropped by the `start` and `end` indices.
 
-**Note that modifying the new `Buffer` slice will modify the memory in the
-original `Buffer` because the allocated memory of the two objects overlap.**
+**Note:** Modifying the new `Buffer` slice will modify the memory in the
+original `Buffer` because the allocated memory of the two objects overlap.
 
 Example: Create a `Buffer` with the ASCII alphabet, take a slice, and then modify
 one byte from the original `Buffer`

doc/api/child_process.md

@@ -163,9 +163,9 @@ exec('echo "The \\$HOME variable is $HOME"');
 //The $HOME variable is escaped in the first instance, but not in the second
 ```
 
-**Note: Never pass unsanitised user input to this function. Any input
+**Note:** Never pass unsanitised user input to this function. Any input
 containing shell metacharacters may be used to trigger arbitrary command
-execution.**
+execution.
 
 ```js
 const exec = require('child_process').exec;
@@ -211,8 +211,8 @@ If `timeout` is greater than `0`, the parent will send the signal
 identified by the `killSignal` property (the default is `'SIGTERM'`) if the
 child runs longer than `timeout` milliseconds.
 
-*Note: Unlike the exec(3) POSIX system call, `child_process.exec()` does not
-replace the existing process and uses a shell to execute the command.*
+**Note:** Unlike the exec(3) POSIX system call, `child_process.exec()` does not
+replace the existing process and uses a shell to execute the command.
 
 If this method is invoked as its [`util.promisify()`][]ed version, it returns
 a Promise for an object with `stdout` and `stderr` properties.
@@ -348,8 +348,8 @@ parent process using the file descriptor (fd) identified using the
 environment variable `NODE_CHANNEL_FD` on the child process. The input and
 output on this fd is expected to be line delimited JSON objects.
 
-*Note: Unlike the fork(2) POSIX system call, `child_process.fork()` does
-not clone the current process.*
+**Note:** Unlike the fork(2) POSIX system call, `child_process.fork()` does
+not clone the current process.
 
 ### child_process.spawn(command[, args][, options])
 <!-- YAML
@@ -387,9 +387,9 @@ The `child_process.spawn()` method spawns a new process using the given
 `command`, with command line arguments in `args`. If omitted, `args` defaults
 to an empty array.
 
-**Note: If the `shell` option is enabled, do not pass unsanitised user input to
+**Note:** If the `shell` option is enabled, do not pass unsanitised user input to
 this function. Any input containing shell metacharacters may be used to
-trigger arbitrary command execution.**
+trigger arbitrary command execution.
 
 A third argument may be used to specify additional options, with these defaults:
 
@@ -476,13 +476,13 @@ child.on('error', (err) => {
 });
 ```
 
-*Note: Certain platforms (macOS, Linux) will use the value of `argv[0]` for the
-process title while others (Windows, SunOS) will use `command`.*
+**Note:** Certain platforms (macOS, Linux) will use the value of `argv[0]` for
+the process title while others (Windows, SunOS) will use `command`.
 
-*Note: Node.js currently overwrites `argv[0]` with `process.execPath` on
+**Note:** Node.js currently overwrites `argv[0]` with `process.execPath` on
 startup, so `process.argv[0]` in a Node.js child process will not match the
 `argv0` parameter passed to `spawn` from the parent, retrieve it with the
-`process.argv0` property instead.*
+`process.argv0` property instead.
 
 #### options.detached
 <!-- YAML
@@ -673,9 +673,11 @@ The `child_process.execFileSync()` method is generally identical to
 [`child_process.execFile()`][] with the exception that the method will not return
 until the child process has fully closed. When a timeout has been encountered
 and `killSignal` is sent, the method won't return until the process has
-completely exited. *Note that if the child process intercepts and handles
-the `SIGTERM` signal and does not exit, the parent process will still wait
-until the child process has exited.*
+completely exited.
+
+**Note:** If the child process intercepts and handles the `SIGTERM` signal and
+does not exit, the parent process will still wait until the child process has
+exited.
 
 If the process times out, or has a non-zero exit code, this method ***will***
 throw.  The [`Error`][] object will contain the entire result from
@@ -729,9 +731,9 @@ If the process times out, or has a non-zero exit code, this method ***will***
 throw.  The [`Error`][] object will contain the entire result from
 [`child_process.spawnSync()`][]
 
-**Note: Never pass unsanitised user input to this function. Any input
+**Note:** Never pass unsanitised user input to this function. Any input
 containing shell metacharacters may be used to trigger arbitrary command
-execution.**
+execution.
 
 ### child_process.spawnSync(command[, args][, options])
 <!-- YAML
@@ -789,9 +791,9 @@ completely exited. Note that if the process intercepts and handles the
 `SIGTERM` signal and doesn't exit, the parent process will wait until the child
 process has exited.
 
-**Note: If the `shell` option is enabled, do not pass unsanitised user input to
-this function. Any input containing shell metacharacters may be used to
-trigger arbitrary command execution.**
+**Note:** If the `shell` option is enabled, do not pass unsanitised user input
+to this function. Any input containing shell metacharacters may be used to
+trigger arbitrary command execution.
 
 ## Class: ChildProcess
 <!-- YAML
@@ -838,7 +840,7 @@ The `'error'` event is emitted whenever:
 2. The process could not be killed, or
 3. Sending a message to the child process failed.
 
-*Note*: The `'exit'` event may or may not fire after an error has occurred.
+**Note:** 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 against accidentally invoking handler functions multiple times.
 
@@ -1166,8 +1168,8 @@ tracking when the socket is destroyed. To indicate this, the `.connections`
 property becomes `null`. It is recommended not to use `.maxConnections` when
 this occurs.
 
-*Note: this function uses [`JSON.stringify()`][] internally to serialize the
-`message`.*
+**Note:** This function uses [`JSON.stringify()`][] internally to serialize the
+`message`.
 
 ### child.stderr
 <!-- YAML

doc/api/cli.md

@@ -144,7 +144,7 @@ added: REPLACEME
 
 Emit pending deprecation warnings.
 
-*Note*: Pending deprecations are generally identical to a runtime deprecation
+**Note:** Pending deprecations are generally identical to a runtime deprecation
 with the notable exception that they are turned *off* by default and will not
 be emitted unless either the `--pending-deprecation` command line flag, or the
 `NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations
@@ -278,8 +278,8 @@ added: v0.1.3
 
 Print v8 command line options.
 
-Note: v8 options allow words to be separated by both dashes (`-`) or underscores
-(`_`).
+**Note:** V8 options allow words to be separated by both dashes (`-`) or
+underscores (`_`).
 
 For example, `--stack-trace-limit` is equivalent to `--stack_trace_limit`.
 
@@ -382,7 +382,7 @@ added: v0.1.32
 
 `':'`-separated list of directories prefixed to the module search path.
 
-_Note: on Windows, this is a `';'`-separated list instead._
+**Note:** On Windows, this is a `';'`-separated list instead.
 
 
 ### `NODE_DISABLE_COLORS=1`
@@ -453,7 +453,7 @@ added: REPLACEME
 
 When set to `1`, emit pending deprecation warnings.
 
-*Note*: Pending deprecations are generally identical to a runtime deprecation
+**Note:** Pending deprecations are generally identical to a runtime deprecation
 with the notable exception that they are turned *off* by default and will not
 be emitted unless either the `--pending-deprecation` command line flag, or the
 `NODE_PENDING_DEPRECATION=1` environment variable, is set. Pending deprecations
@@ -512,7 +512,7 @@ added: v7.7.0
 If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's directory
 containing trusted certificates.
 
-Note: Be aware that unless the child environment is explicitly set, this
+**Note:** Be aware that unless the child environment is explicitly set, this
 evironment variable will be inherited by any child processes, and if they use
 OpenSSL, it may cause them to trust the same CAs as node.
 
@@ -524,7 +524,7 @@ added: v7.7.0
 If `--use-openssl-ca` is enabled, this overrides and sets OpenSSL's file
 containing trusted certificates.
 
-Note: Be aware that unless the child environment is explicitly set, this
+**Note:** Be aware that unless the child environment is explicitly set, this
 evironment variable will be inherited by any child processes, and if they use
 OpenSSL, it may cause them to trust the same CAs as node.
 

doc/api/cluster.md

@@ -95,7 +95,7 @@ Node.js process and a cluster worker differs:
    port is random the first time, but predictable thereafter. To listen
    on a unique port, generate a port number based on the cluster worker ID.
 
-*Note*: Node.js does not provide routing logic. It is, therefore important to
+**Note:** Node.js does not provide routing logic. It is, therefore important to
 design an application such that it does not rely too heavily on in-memory data
 objects for things like sessions and login.
 

doc/api/console.md

@@ -121,8 +121,8 @@ console.assert(false, 'Whoops %s', 'didn\'t work');
 // AssertionError: Whoops didn't work
 ```
 
-*Note: the `console.assert()` method is implemented differently in Node.js
-than the `console.assert()` method [available in browsers][web-api-assert].*
+**Note:** The `console.assert()` method is implemented differently in Node.js
+than the `console.assert()` method [available in browsers][web-api-assert].
 
 Specifically, in browsers, calling `console.assert()` with a falsy
 assertion will cause the `message` to be printed to the console without
@@ -282,10 +282,10 @@ console.timeEnd('100-elements');
 // prints 100-elements: 225.438ms
 ```
 
-*Note: As of Node.js v6.0.0, `console.timeEnd()` deletes the timer to avoid
+**Note:** As of Node.js v6.0.0, `console.timeEnd()` deletes the timer to avoid
 leaking it. On older versions, the timer persisted. This allowed
 `console.timeEnd()` to be called multiple times for the same label. This
-functionality was unintended and is no longer supported.*
+functionality was unintended and is no longer supported.
 
 ### console.trace([message][, ...args])
 <!-- YAML

doc/api/crypto.md

@@ -1820,7 +1820,7 @@ comparing HMAC digests or secret values like authentication cookies or
 `a` and `b` must both be `Buffer`s, `TypedArray`s, or `DataView`s, and they
 must have the same length.
 
-**Note**: Use of `crypto.timingSafeEqual` does not guarantee that the
+**Note:** Use of `crypto.timingSafeEqual` does not guarantee that the
 *surrounding* code is timing-safe. Care should be taken to ensure that the
 surrounding code does not introduce timing vulnerabilities.
 

doc/api/deprecations.md

@@ -531,8 +531,8 @@ Type: Documentation-only
 The `http` module `ServerResponse.prototype.writeHeader()` API has been
 deprecated. Please use `ServerResponse.prototype.writeHead()` instead.
 
-*Note*: The `ServerResponse.prototype.writeHeader()` method was never documented
-as an officially supported API.
+**Note:** The `ServerResponse.prototype.writeHeader()` method was never
+documented as an officially supported API.
 
 <a id="DEP0064"></a>
 ### DEP0064: tls.createSecurePair()
@@ -568,8 +568,8 @@ properties have been deprecated. Please instead use one of the public methods
 `outgoingMessage.removeHeader()`, `outgoingMessage.setHeader()`) for working
 with outgoing headers.
 
-*Note*: `outgoingMessage._headers` and `outgoingMessage._headerNames` were never
-documented as officially supported properties.
+**Note:** `outgoingMessage._headers` and `outgoingMessage._headerNames` were
+never documented as officially supported properties.
 
 <a id="DEP0067"></a>
 ### DEP0067: OutgoingMessage.prototype.\_renderHeaders
@@ -579,7 +579,7 @@ Type: Documentation-only
 The `http` module `OutgoingMessage.prototype._renderHeaders()` API has been
 deprecated.
 
-*Note*: `OutgoingMessage.prototype._renderHeaders` was never documented as
+**Note:** `OutgoingMessage.prototype._renderHeaders` was never documented as
 an officially supported API.
 
 <a id="DEP0068"></a>
@@ -598,7 +598,7 @@ Type: Documentation-only
 The DebugContext will be removed in V8 soon and will not be available in Node
 10+.
 
-*Note*: DebugContext was an experimental API.
+**Note:** DebugContext was an experimental API.
 
 [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
 [`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array

doc/api/domain.md

@@ -115,7 +115,7 @@ if (cluster.isMaster) {
     d.on('error', (er) => {
       console.error(`error ${er.stack}`);
 
-      // Note: we're in dangerous territory!
+      // Note: We're in dangerous territory!
       // By definition, something unexpected occurred,
       // which we probably didn't want.
       // Anything can happen now!  Be very careful!

doc/api/events.md

@@ -142,7 +142,7 @@ myEmitter.emit('error', new Error('whoops!'));
 
 To guard against crashing the Node.js process, a listener can be registered
 on the [`process` object's `uncaughtException` event][] or the [`domain`][] module
-can be used. (_Note, however, that the `domain` module has been deprecated_)
+can be used. (Note, however, that the `domain` module has been deprecated.)
 
 ```js
 const myEmitter = new MyEmitter();