From 0ba8ae2c05bd52a66de304567c33cfd81fa96282 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Mon, 5 Feb 2018 21:55:16 -0800 Subject: [PATCH] doc: remove **Note:** tags Remove the various **Note:** prefixes throughout the docs. --- doc/api/addons.md | 2 +- doc/api/async_hooks.md | 12 ++-- doc/api/buffer.md | 18 ++--- doc/api/child_process.md | 68 +++++++++---------- doc/api/cli.md | 40 +++++------ doc/api/cluster.md | 6 +- doc/api/console.md | 9 ++- doc/api/crypto.md | 22 +++--- doc/api/deprecations.md | 26 +++---- doc/api/documentation.md | 6 +- doc/api/errors.md | 2 +- doc/api/fs.md | 107 ++++++++++++++--------------- doc/api/http.md | 16 ++--- doc/api/http2.md | 97 ++++++++++++-------------- doc/api/intl.md | 4 +- doc/api/modules.md | 20 +++--- doc/api/n-api.md | 46 ++++++------- doc/api/net.md | 21 +++--- doc/api/os.md | 18 ++--- doc/api/path.md | 6 +- doc/api/process.md | 127 +++++++++++++++++----------------- doc/api/punycode.md | 2 +- doc/api/querystring.md | 2 +- doc/api/readline.md | 22 +++--- doc/api/stream.md | 143 +++++++++++++++++++-------------------- doc/api/timers.md | 20 +++--- doc/api/tls.md | 84 +++++++++++------------ doc/api/url.md | 18 ++--- doc/api/util.md | 12 ++-- doc/api/v8.md | 4 +- doc/api/vm.md | 18 ++--- doc/api/zlib.md | 17 +++-- 32 files changed, 493 insertions(+), 522 deletions(-) diff --git a/doc/api/addons.md b/doc/api/addons.md index c6802530f6dc67..385f64d955266e 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -115,7 +115,7 @@ specifically to compile Node.js Addons. } ``` -*Note*: A version of the `node-gyp` utility is bundled and distributed with +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 diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index e0922fcd1134f5..d854d737dcec20 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -306,8 +306,8 @@ set to the `asyncId` of a parent Promise, if there is one, and `undefined` otherwise. For example, in the case of `b = a.then(handler)`, `a` is considered a parent Promise of `b`. -*Note*: In some cases the resource object is reused for performance reasons, -it is thus not safe to use it as a key in a `WeakMap` or add properties to it. +In some cases the resource object is reused for performance reasons, it is +thus not safe to use it as a key in a `WeakMap` or add properties to it. ###### Asynchronous context example @@ -377,9 +377,9 @@ destroy: 9 destroy: 5 ``` -*Note*: As illustrated in the example, `executionAsyncId()` and `execution` -each specify the value of the current execution context; which is delineated by -calls to `before` and `after`. +As illustrated in the example, `executionAsyncId()` and `execution` each specify +the value of the current execution context; which is delineated by calls to +`before` and `after`. Only using `execution` to graph resource allocation results in the following: @@ -599,7 +599,7 @@ own resources. The `init` hook will trigger when an `AsyncResource` is instantiated. -*Note*: `before` and `after` calls must be unwound in the same order that they +The `before` and `after` calls must be unwound in the same order that they are called. Otherwise, an unrecoverable exception will occur and the process will abort. diff --git a/doc/api/buffer.md b/doc/api/buffer.md index 5e72e3bd969b4f..ec2c409ba59c6e 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -195,10 +195,10 @@ The character encodings currently supported by Node.js include: * `'hex'` - Encode each byte as two hexadecimal characters. -*Note*: Today's browsers follow the [WHATWG Encoding Standard][] 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 -specification it is possible that the server actually returned +Modern Web browsers follow the [WHATWG Encoding Standard][] 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 specification it is possible that the server actually returned win-1252-encoded data, and using `'latin1'` encoding may incorrectly decode the characters. @@ -702,9 +702,9 @@ 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*: 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. +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. Example: @@ -1948,8 +1948,8 @@ offset and cropped by the `start` and `end` indices. Specifying `end` greater than [`buf.length`] will return the same result as that of `end` equal to [`buf.length`]. -*Note*: Modifying the new `Buffer` slice will modify the memory in the -original `Buffer` because the allocated memory of the two objects overlap. +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` diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 715eb9d269c38d..768eb91a83de77 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -170,9 +170,8 @@ exec('echo "The \\$HOME variable is $HOME"'); //The $HOME variable is escaped in the first instance, but not in the second ``` -*Note*: Never pass unsanitized user input to this function. Any input -containing shell metacharacters may be used to trigger arbitrary command -execution. +**Never pass unsanitized user input to this function. Any input containing shell +metacharacters may be used to trigger arbitrary command execution.** ```js const { exec } = require('child_process'); @@ -218,8 +217,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. +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. In case of an @@ -316,9 +315,9 @@ async function getVersion() { getVersion(); ``` -*Note*: If the `shell` option is enabled, do not pass unsanitized user input -to this function. Any input containing shell metacharacters may be used to -trigger arbitrary command execution. +**If the `shell` option is enabled, do not pass unsanitized user input to this +function. Any input containing shell metacharacters may be used to trigger +arbitrary command execution.** ### child_process.fork(modulePath[, args][, options]) -*Note*: Usage of `util.inherits()` is discouraged. Please use the ES6 `class` -and `extends` keywords to get language level inheritance support. Also 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} @@ -812,7 +810,7 @@ with ICU and using the full ICU data (see [Internationalization][]). | `'shift_jis'` | `'csshiftjis'`, `'ms932'`, `'ms_kanji'`, `'shift-jis'`, `'sjis'`, `'windows-31j'`, `'x-sjis'` | | `'euc-kr'` | `'cseuckr'`, `'csksc56011987'`, `'iso-ir-149'`, `'korean'`, `'ks_c_5601-1987'`, `'ks_c_5601-1989'`, `'ksc5601'`, `'ksc_5601'`, `'windows-949'` | -*Note*: The `'iso-8859-16'` encoding listed in the [WHATWG Encoding Standard][] +The `'iso-8859-16'` encoding listed in the [WHATWG Encoding Standard][] is not supported. ### new TextDecoder([encoding[, options]]) diff --git a/doc/api/v8.md b/doc/api/v8.md index c9d2512fddff2f..e4e3de78ced495 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -9,7 +9,7 @@ built into the Node.js binary. It can be accessed using: const v8 = require('v8'); ``` -*Note*: The APIs and implementation are subject to change at any time. +The APIs and implementation are subject to change at any time. ## v8.cachedDataVersionTag()