doc: make the style of notes consistent

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

PR-URL: https://github.com/nodejs/node/pull/13133
Fixes: https://github.com/nodejs/node/issues/13131
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>

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

@@ -290,8 +290,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`.
 
@@ -394,7 +394,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`
@@ -525,7 +525,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.
 
@@ -537,7 +537,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/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

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();

doc/api/fs.md

@@ -194,7 +194,7 @@ filesystems that allow for non-UTF-8 filenames. For most typical
 uses, working with paths as Buffers will be unnecessary, as the string
 API converts to and from UTF-8 automatically.
 
-*Note* that on certain file systems (such as NTFS and HFS+) filenames
+*Note*: On certain file systems (such as NTFS and HFS+) filenames
 will always be encoded as UTF-8. On such file systems, passing
 non-UTF-8 encoded Buffers to `fs` functions will not work as expected.
 
@@ -1546,8 +1546,8 @@ On Linux, positional writes don't work when the file is opened in append mode.
 The kernel ignores the position argument and always appends the data to
 the end of the file.
 
-*Note*: The behavior of `fs.open()` is platform-specific for some flags. As such,
-opening a directory on macOS and Linux with the `'a+'` flag - see example
+*Note*: The behavior of `fs.open()` is platform-specific for some flags. As
+such, opening a directory on macOS and Linux with the `'a+'` flag - see example
 below - will return an error. In contrast, on Windows and FreeBSD, a file
 descriptor will be returned.
 
@@ -2156,9 +2156,9 @@ effectively stopping watching of `filename`.
 Calling `fs.unwatchFile()` with a filename that is not being watched is a
 no-op, not an error.
 
-*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile()` and `fs.unwatchFile()`.
-`fs.watch()` should be used instead of `fs.watchFile()` and `fs.unwatchFile()`
-when possible.
+*Note*: [`fs.watch()`][] is more efficient than `fs.watchFile()` and
+`fs.unwatchFile()`.  `fs.watch()` should be used instead of `fs.watchFile()`
+and `fs.unwatchFile()` when possible.
 
 ## fs.utimes(path, atime, mtime, callback)
 <!-- YAML
@@ -2185,7 +2185,7 @@ changes:
 
 Change file timestamps of the file referenced by the supplied path.
 
-Note: the arguments `atime` and `mtime` of the following related functions
+*Note*: The arguments `atime` and `mtime` of the following related functions
 follow these rules:
 
 - The value should be a Unix timestamp in seconds. For example, `Date.now()`
@@ -2366,11 +2366,12 @@ These stat objects are instances of `fs.Stat`.
 To be notified when the file was modified, not just accessed, it is necessary
 to compare `curr.mtime` and `prev.mtime`.
 
-*Note*: when an `fs.watchFile` operation results in an `ENOENT` error, it will
- invoke the listener once, with all the fields zeroed (or, for dates, the Unix
- Epoch). In Windows, `blksize` and `blocks` fields will be `undefined`, instead
- of zero. If the file is created later on, the listener will be called again,
- with the latest stat objects. This is a change in functionality since v0.10.
+*Note*: When an `fs.watchFile` operation results in an `ENOENT` error, it
+will invoke the listener once, with all the fields zeroed (or, for dates, the
+Unix Epoch). In Windows, `blksize` and `blocks` fields will be `undefined`,
+instead of zero. If the file is created later on, the listener will be called
+again, with the latest stat objects. This is a change in functionality since
+v0.10.
 
 *Note*: [`fs.watch()`][] is more efficient than `fs.watchFile` and
 `fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and
@@ -2577,8 +2578,9 @@ Synchronous versions of [`fs.write()`][]. Returns the number of bytes written.
 
 ## FS Constants
 
-The following constants are exported by `fs.constants`. **Note:** Not every
-constant will be available on every operating system.
+The following constants are exported by `fs.constants`.
+
+*Note*: Not every constant will be available on every operating system.
 
 ### File Access Constants
 

doc/api/http.md

@@ -268,8 +268,8 @@ Until the data is consumed, the `'end'` event will not fire.  Also, until
 the data is read it will consume memory that can eventually lead to a
 'process out of memory' error.
 
-Note: Node.js does not check whether Content-Length and the length of the body
-which has been transmitted are equal or not.
+*Note*: Node.js does not check whether Content-Length and the length of the
+body which has been transmitted are equal or not.
 
 The request implements the [Writable Stream][] interface. This is an
 [`EventEmitter`][] with the following events:
@@ -765,7 +765,7 @@ Begin accepting connections on the specified `port` and `hostname`. If the
 [unspecified IPv6 address][] (`::`) when IPv6 is available, or the
 [unspecified IPv4 address][] (`0.0.0.0`) otherwise.
 
-*Note*: in most operating systems, listening to the
+*Note*: In most operating systems, listening to the
 [unspecified IPv6 address][] (`::`) may cause the `net.Server` to also listen on
 the [unspecified IPv4 address][] (`0.0.0.0`).
 
@@ -1177,7 +1177,7 @@ the second parameter specifies how to encode it into a byte stream.
 By default the `encoding` is `'utf8'`. `callback` will be called when this chunk
 of data is flushed.
 
-**Note**: This is the raw HTTP body and has nothing to do with
+*Note*: This is the raw HTTP body and has nothing to do with
 higher-level multi-part body encodings that may be used.
 
 The first time [`response.write()`][] is called, it will send the buffered

doc/api/modules.md

@@ -348,9 +348,9 @@ If this was in a folder at `./some-library`, then
 
 This is the extent of Node.js's awareness of package.json files.
 
-Note: If the file specified by the `"main"` entry of `package.json` is missing
-and can not be resolved, Node.js will report the entire module as missing with
-the default error:
+*Note*: If the file specified by the `"main"` entry of `package.json` is
+missing and can not be resolved, Node.js will report the entire module as
+missing with the default error:
 
 ```txt
 Error: Cannot find module 'some-library'
@@ -401,8 +401,9 @@ same module resolution semantics.
 
 If the `NODE_PATH` environment variable is set to a colon-delimited list
 of absolute paths, then Node.js will search those paths for modules if they
-are not found elsewhere.  (Note: On Windows, `NODE_PATH` is delimited by
-semicolons instead of colons.)
+are not found elsewhere.
+
+*Note*: On Windows, `NODE_PATH` is delimited by semicolons instead of colons.
 
 `NODE_PATH` was originally created to support loading modules from
 varying paths before the current [module resolution][] algorithm was frozen.
@@ -627,10 +628,10 @@ added: v0.5.1
 The `module.require` method provides a way to load a module as if
 `require()` was called from the original module.
 
-*Note*: In order to do this, it is necessary to get a reference to the `module`
-object.  Since `require()` returns the `module.exports`, and the `module` is
-typically *only* available within a specific module's code, it must be
-explicitly exported in order to be used.
+*Note*: In order to do this, it is necessary to get a reference to the
+`module` object.  Since `require()` returns the `module.exports`, and the
+`module` is typically *only* available within a specific module's code, it must
+be explicitly exported in order to be used.
 
 [`Error`]: errors.html#errors_class_error
 [module resolution]: #modules_all_together

doc/api/n-api.md

@@ -241,7 +241,7 @@ typedef struct napi_extended_error_info {
 [`napi_get_last_error_info`][] returns the information for the last
 N-API call that was made.
 
-**Note:** Do not rely on the content or format of any of the extended
+*Note*: Do not rely on the content or format of any of the extended
 information as it is not subject to SemVer and may change at any time.
 It is intended only for logging purposes.
 
@@ -263,7 +263,7 @@ Returns `napi_ok` if the API succeeded.
 This API retrieves a `napi_extended_error_info` structure with information
 about the last error that occured.
 
-**Note:** Do not rely on the content or format of any of the extended
+*Note*: Do not rely on the content or format of any of the extended
 information as it is not subject to SemVer and may change at any time.
 It is intended only for logging purposes.
 
@@ -1138,7 +1138,7 @@ This API allocates a `node::Buffer` object and initializes it with data
 backed by the passed in buffer. While this is still a fully-supported data
 structure, in most cases using a TypedArray will suffice.
 
-**Note:** For Node.js >=4 `Buffers` are Uint8Arrays.
+*Note*: For Node.js >=4 `Buffers` are Uint8Arrays.
 
 #### *napi_create_function*
 <!-- YAML
@@ -2497,7 +2497,7 @@ This API allows an add-on author to create a function object in native code.
 This is the primary mechanism to allow calling *into* the add-on's native code
 *from* Javascript.
 
-**Note:** The newly created function is not automatically visible from
+*Note*: The newly created function is not automatically visible from
 script after this call. Instead, a property must be explicitly set on any
 object that is visible to JavaScript, in order for the function to be accessible
 from script.
@@ -2530,7 +2530,7 @@ const myaddon = require('./addon');
 myaddon.sayHello();
 ```
 
-**Note:**  The string passed to require is not necessarily the name passed into
+*Note*: The string passed to require is not necessarily the name passed into
 `NAPI_MODULE` in the earlier snippet but the name of the target in `binding.gyp`
 responsible for creating the `.node` file.
 

doc/api/net.md

@@ -185,10 +185,11 @@ by the OS through sysctl settings such as `tcp_max_syn_backlog` and `somaxconn`
 on Linux. The default value of this parameter is 511 (not 512).
 
 
-Note:
+*Note*:
 
 * All [`net.Socket`][] are set to `SO_REUSEADDR` (See [socket(7)][] for
   details).
+
 * The `server.listen()` method may be called multiple times. Each
   subsequent call will *re-open* the server using the provided options.
 
@@ -294,7 +295,7 @@ If `host` is omitted, the server will accept connections on the
 [unspecified IPv6 address][] (`::`) when IPv6 is available, or the
 [unspecified IPv4 address][] (`0.0.0.0`) otherwise.
 
-*Note*: in most operating systems, listening to the
+*Note*: In most operating systems, listening to the
 [unspecified IPv6 address][] (`::`) may cause the `net.Server` to also listen on
 the [unspecified IPv4 address][] (`0.0.0.0`).
 
@@ -852,7 +853,7 @@ Possible signatures:
 * [`net.createConnection(port[, host][, connectListener])`][`net.createConnection(port, host)`]
   for TCP connections.
 
-*Note*: the [`net.connect()`][] function is an alias to this function.
+*Note*: The [`net.connect()`][] function is an alias to this function.
 
 ### net.createConnection(options[, connectListener])
 <!-- YAML

doc/api/os.md

@@ -165,8 +165,8 @@ For example:
 ]
 ```
 
-*Note*: Because `nice` values are UNIX-specific, on Windows the `nice` values of
-all processors are always 0.
+*Note*: Because `nice` values are UNIX-specific, on Windows the `nice` values
+of all processors are always 0.
 
 ## os.endianness()
 <!-- YAML
@@ -328,8 +328,8 @@ added: v0.3.3
 The `os.release()` method returns a string identifying the operating system
 release.
 
-*Note*: On POSIX systems, the operating system release is determined by calling
-uname(3). On Windows, `GetVersionExW()` is used. Please see
+*Note*: On POSIX systems, the operating system release is determined by
+calling uname(3). On Windows, `GetVersionExW()` is used. Please see
 https://en.wikipedia.org/wiki/Uname#Examples for more information.
 
 ## os.tmpdir()
@@ -406,8 +406,9 @@ operating system response.
 
 ## OS Constants
 
-The following constants are exported by `os.constants`. **Note:** Not all
-constants will be available on every operating system.
+The following constants are exported by `os.constants`.
+
+*Note*: Not all constants will be available on every operating system.
 
 ### Signal Constants
 <!-- YAML

doc/api/process.md

@@ -1005,7 +1005,7 @@ if (process.getegid) {
 ```
 
 *Note*: This function is only available on POSIX platforms (i.e. not Windows
-or Android)
+or Android).
 
 ## process.geteuid()
 <!-- YAML
@@ -1023,8 +1023,8 @@ if (process.geteuid) {
 }
 ```
 
-*Note*: This function is only available on POSIX platforms (i.e. not Windows or
-Android)
+*Note*: This function is only available on POSIX platforms (i.e. not Windows
+or Android).
 
 ## process.getgid()
 <!-- YAML
@@ -1042,8 +1042,8 @@ if (process.getgid) {
 }
 ```
 
-*Note*: This function is only available on POSIX platforms (i.e. not Windows or
-Android)
+*Note*: This function is only available on POSIX platforms (i.e. not Windows
+or Android).
 
 
 ## process.getgroups()
@@ -1057,8 +1057,8 @@ The `process.getgroups()` method returns an array with the supplementary group
 IDs. POSIX leaves it unspecified if the effective group ID is included but
 Node.js ensures it always is.
 
-*Note*: This function is only available on POSIX platforms (i.e. not Windows or
-Android)
+*Note*: This function is only available on POSIX platforms (i.e. not Windows
+or Android).
 
 ## process.getuid()
 <!-- YAML
@@ -1076,8 +1076,8 @@ if (process.getuid) {
 }
 ```
 
-*Note*: This function is only available on POSIX platforms (i.e. not Windows or
-Android)
+*Note*: This function is only available on POSIX platforms (i.e. not Windows
+or Android).
 
 ## process.hrtime([time])
 <!-- YAML
@@ -1139,8 +1139,8 @@ process.setgid(1000);                     // drop root gid
 console.log(process.getgroups());         // [ 27, 30, 46, 1000 ]
 ```
 
-*Note*: This function is only available on POSIX platforms (i.e. not Windows or
-Android)
+*Note*: This function is only available on POSIX platforms (i.e. not Windows
+or Android).
 
 ## process.kill(pid[, signal])
 <!-- YAML
@@ -1162,9 +1162,9 @@ case, a signal of `0` can be used to test for the existence of a process.
 Windows platforms will throw an error if the `pid` is used to kill a process
 group.
 
-*Note*:Even though the name of this function is `process.kill()`, it is really
-just a signal sender, like the `kill` system call.  The signal sent may do
-something other than kill the target process.
+*Note*: Even though the name of this function is `process.kill()`, it is
+really just a signal sender, like the `kill` system call.  The signal sent may
+do something other than kill the target process.
 
 For example:
 
@@ -1181,8 +1181,8 @@ setTimeout(() => {
 process.kill(process.pid, 'SIGHUP');
 ```
 
-*Note*: When `SIGUSR1` is received by a Node.js process, Node.js will start the
-debugger, see [Signal Events][].
+*Note*: When `SIGUSR1` is received by a Node.js process, Node.js will start
+the debugger, see [Signal Events][].
 
 ## process.mainModule
 <!-- YAML
@@ -1331,7 +1331,7 @@ function definitelyAsync(arg, cb) {
 }
 ```
 
-*Note*: the next tick queue is completely drained on each pass of the
+*Note*: The next tick queue is completely drained on each pass of the
 event loop **before** additional I/O is processed.  As a result,
 recursively setting nextTick callbacks will block any I/O from
 happening, just like a `while(true);` loop.
@@ -1430,7 +1430,7 @@ If Node.js was not spawned with an IPC channel, `process.send()` will be
 `undefined`.
 
 *Note*: This function uses [`JSON.stringify()`][] internally to serialize the
-`message`.*
+`message`.
 
 ## process.setegid(id)
 <!-- YAML
@@ -1456,8 +1456,8 @@ if (process.getegid && process.setegid) {
 }
 ```
 
-*Note*: This function is only available on POSIX platforms (i.e. not Windows or
-Android)
+*Note*: This function is only available on POSIX platforms (i.e. not Windows
+or Android).
 
 
 ## process.seteuid(id)
@@ -1484,8 +1484,8 @@ if (process.geteuid && process.seteuid) {
 }
 ```
 
-*Note*: This function is only available on POSIX platforms (i.e. not Windows or
-Android)
+*Note*: This function is only available on POSIX platforms (i.e. not Windows
+or Android).
 
 ## process.setgid(id)
 <!-- YAML
@@ -1511,8 +1511,8 @@ if (process.getgid && process.setgid) {
 }
 ```
 
-*Note*: This function is only available on POSIX platforms (i.e. not Windows or
-Android)
+*Note*: This function is only available on POSIX platforms (i.e. not Windows
+or Android).
 
 ## process.setgroups(groups)
 <!-- YAML
@@ -1527,8 +1527,8 @@ to have `root` or the `CAP_SETGID` capability.
 
 The `groups` array can contain numeric group IDs, group names or both.
 
-*Note*: This function is only available on POSIX platforms (i.e. not Windows or
-Android)
+*Note*: This function is only available on POSIX platforms (i.e. not Windows
+or Android).
 
 ## process.setuid(id)
 <!-- YAML
@@ -1552,8 +1552,8 @@ if (process.getuid && process.setuid) {
 }
 ```
 
-*Note*: This function is only available on POSIX platforms (i.e. not Windows or
-Android)
+*Note*: This function is only available on POSIX platforms (i.e. not Windows
+or Android).
 
 
 ## process.stderr
@@ -1565,7 +1565,7 @@ The `process.stderr` property returns a stream connected to
 stream) unless fd `2` refers to a file, in which case it is
 a [Writable][] stream.
 
-Note: `process.stderr` differs from other Node.js streams in important ways,
+*Note*: `process.stderr` differs from other Node.js streams in important ways,
 see [note on process I/O][] for more information.
 
 ## process.stdin
@@ -1617,7 +1617,7 @@ For example, to copy process.stdin to process.stdout:
 process.stdin.pipe(process.stdout);
 ```
 
-Note: `process.stdout` differs from other Node.js streams in important ways,
+*Note*: `process.stdout` differs from other Node.js streams in important ways,
 see [note on process I/O][] for more information.
 
 ### A note on process I/O
@@ -1680,14 +1680,14 @@ The `process.title` property returns the current process title (i.e. returns
 the current value of `ps`). Assigning a new value to `process.title` modifies
 the current value of `ps`.
 
-*Note*: When a new value is assigned, different platforms will impose different
-maximum length restrictions on the title. Usually such restrictions are quite
-limited. For instance, on Linux and macOS, `process.title` is limited to the
-size of the binary name plus the length of the command line arguments because
-setting the `process.title` overwrites the `argv` memory of the process.
-Node.js v0.8 allowed for longer process title strings by also overwriting the
-`environ` memory but that was potentially insecure and confusing in some
-(rather obscure) cases.
+*Note*: When a new value is assigned, different platforms will impose
+different maximum length restrictions on the title. Usually such restrictions
+are quite limited. For instance, on Linux and macOS, `process.title` is limited
+to the size of the binary name plus the length of the command line arguments
+because setting the `process.title` overwrites the `argv` memory of the
+process.  Node.js v0.8 allowed for longer process title strings by also
+overwriting the `environ` memory but that was potentially insecure and
+confusing in some (rather obscure) cases.
 
 ## process.umask([mask])
 <!-- YAML
@@ -1720,7 +1720,7 @@ added: v0.5.0
 The `process.uptime()` method returns the number of seconds the current Node.js
 process has been running.
 
-*Note*: the return value includes fractions of a second. Use `Math.floor()`
+*Note*: The return value includes fractions of a second. Use `Math.floor()`
 to get whole seconds.
 
 ## process.version

doc/api/readline.md

@@ -27,7 +27,7 @@ rl.question('What do you think of Node.js? ', (answer) => {
 });
 ```
 
-*Note* Once this code is invoked, the Node.js application will not
+*Note*: Once this code is invoked, the Node.js application will not
 terminate until the `readline.Interface` is closed because the interface
 waits for data to be received on the `input` stream.
 

doc/api/stream.md

@@ -893,7 +893,7 @@ A Readable stream in object mode will always return a single item from
 a call to [`readable.read(size)`][stream-read], regardless of the value of the
 `size` argument.
 
-*Note:* If the `readable.read()` method returns a chunk of data, a `'data'`
+*Note*: If the `readable.read()` method returns a chunk of data, a `'data'`
 event will also be emitted.
 
 *Note*: Calling [`stream.read([size])`][stream-read] after the [`'end'`][]
@@ -1346,7 +1346,7 @@ resource.
 *Note*: [Transform][] streams provide their own implementation of the
 [`writable._write()`][stream-_write].
 
-*Note*: **This function MUST NOT be called by application code directly.** It
+*Note*: This function MUST NOT be called by application code directly. It
 should be implemented by child classes, and called only by the internal Writable
 class methods only.
 
@@ -1381,7 +1381,7 @@ user programs.
 * `callback` {Function} A callback function (optionally with an error
   argument) to be invoked when processing is complete for the supplied chunks.
 
-*Note*: **This function MUST NOT be called by application code directly.** It
+*Note*: This function MUST NOT be called by application code directly. It
 should be implemented by child classes, and called only by the internal Writable
 class methods only.
 
@@ -1536,7 +1536,7 @@ const myReadable = new Readable({
 
 * `size` {number} Number of bytes to read asynchronously
 
-*Note*: **This function MUST NOT be called by application code directly.** It
+*Note*: This function MUST NOT be called by application code directly. It
 should be implemented by child classes, and called only by the internal Readable
 class methods only.
 
@@ -1684,10 +1684,10 @@ Because JavaScript does not have support for multiple inheritance, the
 `stream.Duplex` class is extended to implement a [Duplex][] stream (as opposed
 to extending the `stream.Readable` *and* `stream.Writable` classes).
 
-*Note*: The `stream.Duplex` class prototypically inherits from `stream.Readable`
-and parasitically from `stream.Writable`, but `instanceof` will work properly
-for both base classes due to overriding [`Symbol.hasInstance`][]
-on `stream.Writable`.
+*Note*: The `stream.Duplex` class prototypically inherits from
+`stream.Readable` and parasitically from `stream.Writable`, but `instanceof`
+will work properly for both base classes due to overriding
+[`Symbol.hasInstance`][] on `stream.Writable`.
 
 Custom Duplex streams *must* call the `new stream.Duplex([options])`
 constructor and implement *both* the `readable._read()` and
@@ -1916,7 +1916,7 @@ after all data has been output, which occurs after the callback in
 * `callback` {Function} A callback function (optionally with an error
   argument and data) to be called when remaining data has been flushed.
 
-*Note*: **This function MUST NOT be called by application code directly.** It
+*Note*: This function MUST NOT be called by application code directly. It
 should be implemented by child classes, and called only by the internal Readable
 class methods only.
 
@@ -1951,7 +1951,7 @@ user programs.
   argument and data) to be called after the supplied `chunk` has been
   processed.
 
-*Note*: **This function MUST NOT be called by application code directly.** It
+*Note*: This function MUST NOT be called by application code directly. It
 should be implemented by child classes, and called only by the internal Readable
 class methods only.
 

doc/api/tls.md

@@ -488,11 +488,9 @@ changes:
   * `secureContext`: Optional TLS context object created with
     [`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one
     will be created by passing the entire `options` object to
-    `tls.createSecureContext()`. *Note*: In effect, all
-    [`tls.createSecureContext()`][] options can be provided, but they will be
-    _completely ignored_ unless the `secureContext` option is missing.
-  * ...: Optional [`tls.createSecureContext()`][] options can be provided, see
-    the `secureContext` option for more information.
+    `tls.createSecureContext()`.
+  * ...: Optional [`tls.createSecureContext()`][] options that are used if the
+    `secureContext` option is missing, otherwise they are ignored.
 
 Construct a new `tls.TLSSocket` object from an existing TCP socket.
 
@@ -667,8 +665,8 @@ added: v0.11.4
 
 Returns the TLS session ticket or `undefined` if no session was negotiated.
 
-*Note*: This only works with client TLS sockets. Useful only for debugging, for
-session reuse provide `session` option to [`tls.connect()`][].
+*Note*: This only works with client TLS sockets. Useful only for debugging,
+for session reuse provide `session` option to [`tls.connect()`][].
 
 ### tlsSocket.localAddress
 <!-- YAML
@@ -809,12 +807,10 @@ changes:
   * `secureContext`: Optional TLS context object created with
     [`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one
     will be created by passing the entire `options` object to
-    `tls.createSecureContext()`. *Note*: In effect, all
-    [`tls.createSecureContext()`][] options can be provided, but they will be
-    _completely ignored_ unless the `secureContext` option is missing.
+    `tls.createSecureContext()`.
   * `lookup`: {Function} Custom lookup function. Defaults to [`dns.lookup()`][].
-  * ...: Optional [`tls.createSecureContext()`][] options can be provided, see
-    the `secureContext` option for more information.
+  * ...: Optional [`tls.createSecureContext()`][] options that are used if the
+    `secureContext` option is missing, otherwise they are ignored.
 * `callback` {Function}
 
 The `callback` function, if specified, will be added as a listener for the
@@ -905,8 +901,8 @@ added: v0.11.3
 Same as [`tls.connect()`][] except that `port` and `host` can be provided
 as arguments instead of options.
 
-*Note*: A port or host option, if specified, will take precedence over any port
-or host argument.
+*Note*: A port or host option, if specified, will take precedence over any
+port or host argument.
 
 
 ## tls.createSecureContext(options)
@@ -971,8 +967,6 @@ changes:
     preferences instead of the client's. When `true`, causes
     `SSL_OP_CIPHER_SERVER_PREFERENCE` to be set in `secureOptions`, see
     [OpenSSL Options][] for more information.
-    *Note*: [`tls.createServer()`][] sets the default value to `true`, other
-    APIs that create secure contexts leave it unset.
   * `ecdhCurve` {string} A string describing a named curve to use for ECDH key
     agreement or `false` to disable ECDH. Defaults to
     [`tls.DEFAULT_ECDH_CURVE`].  Use [`crypto.getCurves()`][] to obtain a list
@@ -994,9 +988,16 @@ changes:
     [OpenSSL Options][].
   * `sessionIdContext` {string} Optional opaque identifier used by servers to
     ensure session state is not shared between applications. Unused by clients.
-    *Note*: [`tls.createServer()`][] uses a 128 bit truncated SHA1 hash value
-    generated from `process.argv`, other APIs that create secure contexts
-    have no default value.
+
+*Note*:
+
+* [`tls.createServer()`][] sets the default value of the
+  `honorCipherOrder` option to `true`, other APIs that create secure contexts
+  leave it unset.
+
+* [`tls.createServer()`][] uses a 128 bit truncated SHA1 hash value
+  generated from `process.argv` as the default value of the `sessionIdContext`
+  option, other APIs that create secure contexts have no default value.
 
 The `tls.createSecureContext()` method creates a credentials object.
 
@@ -1060,8 +1061,7 @@ changes:
     server will time out. See [SSL_CTX_set_timeout] for more details.
   * `ticketKeys`: A 48-byte `Buffer` instance consisting of a 16-byte prefix,
     a 16-byte HMAC key, and a 16-byte AES key. This can be used to accept TLS
-    session tickets on multiple instances of the TLS server. *Note* that this is
-    automatically shared between `cluster` module workers.
+    session tickets on multiple instances of the TLS server.
   * ...: Any [`tls.createSecureContext()`][] options can be provided. For
     servers, the identity options (`pfx` or `key`/`cert`) are usually required.
 * `secureConnectionListener` {Function}
@@ -1069,6 +1069,9 @@ changes:
 Creates a new [tls.Server][].  The `secureConnectionListener`, if provided, is
 automatically set as a listener for the [`'secureConnection'`][] event.
 
+*Note*: The `ticketKeys` options is automatically shared between `cluster`
+module workers.
+
 The following illustrates a simple echo server:
 
 ```js

doc/api/util.md

@@ -151,9 +151,9 @@ changes:
     description: The `constructor` parameter can refer to an ES6 class now.
 -->
 
-_Note: usage of `util.inherits()` is discouraged. Please use the ES6 `class` and
-`extends` keywords to get language level inheritance support. Also note that
-the two styles are [semantically incompatible][]._
+*Note*: Usage of `util.inherits()` is discouraged. Please use the ES6 `class`
+and `extends` keywords to get language level inheritance support. Also note
+that the two styles are [semantically incompatible][].
 
 * `constructor` {Function}
 * `superConstructor` {Function}

doc/api/zlib.md

@@ -54,8 +54,8 @@ the compression encodings accepted by the client. The [`Content-Encoding`][]
 header is used to identify the compression encodings actually applied to a
 message.
 
-**Note: the examples given below are drastically simplified to show
-the basic concept.**  Using `zlib` encoding can be expensive, and the results
+*Note*: the examples given below are drastically simplified to show
+the basic concept.  Using `zlib` encoding can be expensive, and the results
 ought to be cached.  See [Memory Usage Tuning][] for more information
 on the speed/memory/compression tradeoffs involved in `zlib` usage.
 
@@ -100,7 +100,7 @@ http.createServer((request, response) => {
     acceptEncoding = '';
   }
 
-  // Note: this is not a conformant accept-encoding parser.
+  // Note: This is not a conformant accept-encoding parser.
   // See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
   if (acceptEncoding.match(/\bdeflate\b/)) {
     response.writeHead(200, { 'Content-Encoding': 'deflate' });
@@ -437,7 +437,7 @@ added: v0.5.8
 
 Returns a new [DeflateRaw][] object with an [options][].
 
-**Note:** The zlib library rejects requests for 256-byte windows (i.e.,
+*Note*: The zlib library rejects requests for 256-byte windows (i.e.,
 `{ windowBits: 8 }` in `options`). An `Error` will be thrown when creating
 a [DeflateRaw][] object with this specific value of the `windowBits` option.
 

doc/changelogs/CHANGELOG_V010.md

@@ -70,7 +70,7 @@
   * [io.js](CHANGELOG_IOJS.md)
   * [Archive](CHANGELOG_ARCHIVE.md)
 
-**Note:** Node.js v0.10 is covered by the
+*Note*: Node.js v0.10 is covered by the
 [Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and
 will be maintained until October 2016.
 

doc/changelogs/CHANGELOG_V012.md

@@ -38,7 +38,7 @@
   * [io.js](CHANGELOG_IOJS.md)
   * [Archive](CHANGELOG_ARCHIVE.md)
 
-**Note:** Node.js v0.12 is covered by the
+*Note*: Node.js v0.12 is covered by the
 [Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and
 will be maintained until December 31st, 2016.
 

doc/changelogs/CHANGELOG_V4.md

@@ -57,7 +57,7 @@
   * [Archive](CHANGELOG_ARCHIVE.md)
 
 
-**Note:** Node.js v4 is covered by the
+*Note*: Node.js v4 is covered by the
 [Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and
 will be supported actively until April 2017 and maintained until April 2018.
 

doc/changelogs/CHANGELOG_V5.md

@@ -38,7 +38,7 @@
   * [io.js](CHANGELOG_IOJS.md)
   * [Archive](CHANGELOG_ARCHIVE.md)
 
-**Note:** Official support for the v5 release line is scheduled to expire
+*Note*: Official support for the v5 release line is scheduled to expire
 around June 2016. Users of v5 should upgrade to [Node.js v6](CHANGELOG_V6.md).
 
 <a id="5.12.0"></a>

doc/changelogs/CHANGELOG_V6.md

@@ -45,7 +45,7 @@
   * [io.js](CHANGELOG_IOJS.md)
   * [Archive](CHANGELOG_ARCHIVE.md)
 
-**Note:** Node.js v6 is covered by the
+*Note*: Node.js v6 is covered by the
 [Node.js Long Term Support Plan](https://github.com/nodejs/LTS) and
 will be supported actively until April 2018 and maintained until April 2019.
 

doc/releases.md

@@ -86,7 +86,7 @@ This macro is used to signal an ABI version for native addons. It currently has
 
 The general rule is to bump this version when there are _breaking ABI_ changes and also if there are non-trivial API changes. The rules are not yet strictly defined, so if in doubt, please confer with someone that will have a more informed perspective, such as a member of the NAN team.
 
-**Note** that it is current TSC policy to bump major version when ABI changes. If you see a need to bump `NODE_MODULE_VERSION` then you should consult the TSC. Commits may need to be reverted or a major version bump may need to happen.
+*Note*: It is current TSC policy to bump major version when ABI changes. If you see a need to bump `NODE_MODULE_VERSION` then you should consult the TSC. Commits may need to be reverted or a major version bump may need to happen.
 
 ### 3. Update the Changelog
 
@@ -279,7 +279,8 @@ Use `tools/release.sh` to promote and sign the build. When run, it will perform
 
 If you didn't wait for ARM builds in the previous step before promoting the release, you should re-run `tools/release.sh` after the ARM builds have finished. That will move the ARM artifacts into the correct location. You will be prompted to re-sign SHASUMS256.txt.
 
-Note: it is possible to only sign a release by running `./tools/release.sh -s vX.Y.Z`.
+*Note*: It is possible to only sign a release by running
+`./tools/release.sh -s vX.Y.Z`.
 
 ### 13. Check the Release