From d796bc73488f6b6e5abc24d7d627ef971d1d8c5f Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Mon, 9 Nov 2020 05:44:32 -0800 Subject: [PATCH] doc: update list styles for remark-parse@9 rendering remark-parse@9.0.0 combined with our html.js tool ends a list if a multi-line item does not include indentation. Update our docs for this formatting. I looked around for a lint rule to enforce this but didn't find one readily available. (Happy to be shown that I'm wrong about that!) We may need to write one. PR-URL: https://github.com/nodejs/node/pull/36049 Reviewed-By: Antoine du Hamel Reviewed-By: Daijiro Wachi --- doc/api/addons.md | 31 ++++++++++++++------------- doc/api/assert.md | 2 +- doc/api/async_hooks.md | 16 +++++++------- doc/api/debugger.md | 14 ++++++------- doc/api/dns.md | 10 ++++----- doc/api/fs.md | 44 +++++++++++++++++++-------------------- doc/api/http.md | 6 +++--- doc/api/http2.md | 2 +- doc/api/https.md | 2 +- doc/api/modules.md | 2 +- doc/api/n-api.md | 20 +++++++++--------- doc/api/report.md | 34 +++++++++++++++--------------- doc/api/stream.md | 6 +++--- doc/api/string_decoder.md | 4 ++-- doc/api/tls.md | 18 ++++++++-------- doc/api/util.md | 4 ++-- 16 files changed, 108 insertions(+), 107 deletions(-) diff --git a/doc/api/addons.md b/doc/api/addons.md index 62573f55d06d48..d484e51caeab66 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -154,25 +154,26 @@ they were created. The context-aware addon can be structured to avoid global static data by performing the following steps: + * Define a class which will hold per-addon-instance data and which has a static -member of the form + member of the form ```cpp static void DeleteInstance(void* data) { // Cast `data` to an instance of the class and delete it. } ``` * Heap-allocate an instance of this class in the addon initializer. This can be -accomplished using the `new` keyword. + accomplished using the `new` keyword. * Call `node::AddEnvironmentCleanupHook()`, passing it the above-created -instance and a pointer to `DeleteInstance()`. This will ensure the instance is -deleted when the environment is torn down. + instance and a pointer to `DeleteInstance()`. This will ensure the instance is + deleted when the environment is torn down. * Store the instance of the class in a `v8::External`, and * Pass the `v8::External` to all methods exposed to JavaScript by passing it -to `v8::FunctionTemplate::New()` or `v8::Function::New()` which creates the -native-backed JavaScript functions. The third parameter of -`v8::FunctionTemplate::New()` or `v8::Function::New()` accepts the -`v8::External` and makes it available in the native callback using the -`v8::FunctionCallbackInfo::Data()` method. + to `v8::FunctionTemplate::New()` or `v8::Function::New()` which creates the + native-backed JavaScript functions. The third parameter of + `v8::FunctionTemplate::New()` or `v8::Function::New()` accepts the + `v8::External` and makes it available in the native callback using the + `v8::FunctionCallbackInfo::Data()` method. This will ensure that the per-addon-instance data reaches each binding that can be called from JavaScript. The per-addon-instance data must also be passed into @@ -395,14 +396,14 @@ the appropriate headers automatically. However, there are a few caveats to be aware of: * When `node-gyp` runs, it will detect the specific release version of Node.js -and download either the full source tarball or just the headers. If the full -source is downloaded, addons will have complete access to the full set of -Node.js dependencies. However, if only the Node.js headers are downloaded, then -only the symbols exported by Node.js will be available. + and download either the full source tarball or just the headers. If the full + source is downloaded, addons will have complete access to the full set of + Node.js dependencies. However, if only the Node.js headers are downloaded, + then only the symbols exported by Node.js will be available. * `node-gyp` can be run using the `--nodedir` flag pointing at a local Node.js -source image. Using this option, the addon will have access to the full set of -dependencies. + source image. Using this option, the addon will have access to the full set of + dependencies. ### Loading addons using `require()` diff --git a/doc/api/assert.md b/doc/api/assert.md index 1fd57b6f9f901d..70c03bda3773eb 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -223,7 +223,7 @@ added: v14.2.0 --> * Returns: {Array} of objects containing information about the wrapper functions -returned by [`tracker.calls()`][]. + returned by [`tracker.calls()`][]. * Object {Object} * `message` {string} * `actual` {number} The actual number of times the function was called. diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index cf3fd79ffafc21..93a6ccdfc18879 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -697,14 +697,14 @@ asyncResource.triggerAsyncId(); * `type` {string} The type of async event. * `options` {Object} * `triggerAsyncId` {number} The ID of the execution context that created this - async event. **Default:** `executionAsyncId()`. + async event. **Default:** `executionAsyncId()`. * `requireManualDestroy` {boolean} If set to `true`, disables `emitDestroy` - when the object is garbage collected. This usually does not need to be set - (even if `emitDestroy` is called manually), unless the resource's `asyncId` - is retrieved and the sensitive API's `emitDestroy` is called with it. - When set to `false`, the `emitDestroy` call on garbage collection - will only take place if there is at least one active `destroy` hook. - **Default:** `false`. + when the object is garbage collected. This usually does not need to be set + (even if `emitDestroy` is called manually), unless the resource's `asyncId` + is retrieved and the sensitive API's `emitDestroy` is called with it. + When set to `false`, the `emitDestroy` call on garbage collection + will only take place if there is at least one active `destroy` hook. + **Default:** `false`. Example usage: @@ -785,7 +785,7 @@ never be called. #### `asyncResource.triggerAsyncId()` * Returns: {number} The same `triggerAsyncId` that is passed to the -`AsyncResource` constructor. + `AsyncResource` constructor. ### Using `AsyncResource` for a `Worker` thread pool diff --git a/doc/api/debugger.md b/doc/api/debugger.md index 89980cfbd4a06f..b6dd45c7000b46 100644 --- a/doc/api/debugger.md +++ b/doc/api/debugger.md @@ -115,14 +115,14 @@ To begin watching an expression, type `watch('my_expression')`. The command * `setBreakpoint()`, `sb()`: Set breakpoint on current line * `setBreakpoint(line)`, `sb(line)`: Set breakpoint on specific line * `setBreakpoint('fn()')`, `sb(...)`: Set breakpoint on a first statement in -functions body + functions body * `setBreakpoint('script.js', 1)`, `sb(...)`: Set breakpoint on first line of -`script.js` + `script.js` * `setBreakpoint('script.js', 1, 'num < 4')`, `sb(...)`: Set conditional -breakpoint on first line of `script.js` that only breaks when `num < 4` -evaluates to `true` + breakpoint on first line of `script.js` that only breaks when `num < 4` + evaluates to `true` * `clearBreakpoint('script.js', 1)`, `cb(...)`: Clear breakpoint in `script.js` -on line 1 + on line 1 It is also possible to set a breakpoint in a file (module) that is not loaded yet: @@ -188,11 +188,11 @@ debug> * `backtrace`, `bt`: Print backtrace of current execution frame * `list(5)`: List scripts source code with 5 line context (5 lines before and -after) + after) * `watch(expr)`: Add expression to watch list * `unwatch(expr)`: Remove expression from watch list * `watchers`: List all watchers and their values (automatically listed on each -breakpoint) + breakpoint) * `repl`: Open debugger's repl for evaluation in debugging script's context * `exec expr`: Execute an expression in debugging script's context diff --git a/doc/api/dns.md b/doc/api/dns.md index 7e27bcc216f1d6..e78eddfdb5a9d0 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -226,13 +226,13 @@ changes: The following flags can be passed as hints to [`dns.lookup()`][]. * `dns.ADDRCONFIG`: Limits returned address types to the types of non-loopback -addresses configured on the system. For example, IPv4 addresses are only -returned if the current system has at least one IPv4 address configured. + addresses configured on the system. For example, IPv4 addresses are only + returned if the current system has at least one IPv4 address configured. * `dns.V4MAPPED`: If the IPv6 family was specified, but no IPv6 addresses were -found, then return IPv4 mapped IPv6 addresses. It is not supported -on some operating systems (e.g FreeBSD 10.1). + found, then return IPv4 mapped IPv6 addresses. It is not supported + on some operating systems (e.g FreeBSD 10.1). * `dns.ALL`: If `dns.V4MAPPED` is specified, return resolved IPv6 addresses as -well as IPv4 mapped IPv6 addresses. + well as IPv4 mapped IPv6 addresses. ## `dns.lookupService(address, port, callback)` * `options` {Object} Accepts `options` from [`tls.createServer()`][], - [`tls.createSecureContext()`][] and [`http.createServer()`][]. + [`tls.createSecureContext()`][] and [`http.createServer()`][]. * `requestListener` {Function} A listener to be added to the `'request'` event. * Returns: {https.Server} diff --git a/doc/api/modules.md b/doc/api/modules.md index 31726a9434e4ac..f36406ba0590b9 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -503,7 +503,7 @@ wrapper that looks like the following: By doing this, Node.js achieves a few things: * It keeps top-level variables (defined with `var`, `const` or `let`) scoped to -the module rather than the global object. + the module rather than the global object. * It helps to provide some global-looking variables that are actually specific to the module, such as: * The `module` and `exports` objects that the implementor can use to export diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 6a03ffd3d29d34..aa4598877e2d90 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -858,8 +858,8 @@ typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle, ``` * `[in] handle`: The handle that must be passed to -[`napi_remove_async_cleanup_hook`][] after completion of the asynchronous -cleanup. + [`napi_remove_async_cleanup_hook`][] after completion of the asynchronous + cleanup. * `[in] data`: The data that was passed to [`napi_add_async_cleanup_hook`][]. The body of the function should initiate the asynchronous cleanup actions at the @@ -939,7 +939,7 @@ napi_get_last_error_info(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[out] result`: The `napi_extended_error_info` structure with more -information about the error. + information about the error. Returns `napi_ok` if the API succeeded. @@ -1715,7 +1715,7 @@ NAPI_EXTERN napi_status napi_add_async_cleanup_hook( * `[in] hook`: The function pointer to call at environment teardown. * `[in] arg`: The pointer to pass to `hook` when it gets called. * `[out] remove_handle`: Optional handle that refers to the asynchronous cleanup -hook. + hook. Registers `hook`, which is a function of type [`napi_async_cleanup_hook`][], as a function to be run with the `remove_handle` and `arg` parameters once the @@ -1748,7 +1748,7 @@ NAPI_EXTERN napi_status napi_remove_async_cleanup_hook( ``` * `[in] remove_handle`: The handle to an asynchronous cleanup hook that was -created with [`napi_add_async_cleanup_hook`][]. + created with [`napi_add_async_cleanup_hook`][]. Unregisters the cleanup hook corresponding to `remove_handle`. This will prevent the hook from being executed, unless it has already started executing. @@ -3355,7 +3355,7 @@ napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result) Returns `napi_ok` if the API succeeded. * `napi_invalid_arg` if the type of `value` is not a known ECMAScript type and - `value` is not an External value. + `value` is not an External value. This API represents behavior similar to invoking the `typeof` Operator on the object as defined in [Section 12.5.5][] of the ECMAScript Language @@ -3884,11 +3884,11 @@ napi_get_all_property_names(napi_env env, * `[in] object`: The object from which to retrieve the properties. * `[in] key_mode`: Whether to retrieve prototype properties as well. * `[in] key_filter`: Which properties to retrieve -(enumerable/readable/writable). + (enumerable/readable/writable). * `[in] key_conversion`: Whether to convert numbered property keys to strings. * `[out] result`: A `napi_value` representing an array of JavaScript values -that represent the property names of the object. [`napi_get_array_length`][] and -[`napi_get_element`][] can be used to iterate over `result`. + that represent the property names of the object. [`napi_get_array_length`][] + and [`napi_get_element`][] can be used to iterate over `result`. Returns `napi_ok` if the API succeeded. @@ -4920,7 +4920,7 @@ napi_status napi_check_object_type_tag(napi_env env, * `[in] js_object`: The JavaScript object whose type tag to examine. * `[in] type_tag`: The tag with which to compare any tag found on the object. * `[out] result`: Whether the type tag given matched the type tag on the -object. `false` is also returned if no type tag was found on the object. + object. `false` is also returned if no type tag was found on the object. Returns `napi_ok` if the API succeeded. diff --git a/doc/api/report.md b/doc/api/report.md index b62de913be2b29..9ee65280a8aa41 100644 --- a/doc/api/report.md +++ b/doc/api/report.md @@ -396,15 +396,15 @@ node --report-uncaught-exception --report-on-signal \ ``` * `--report-uncaught-exception` Enables report to be generated on -un-caught exceptions. Useful when inspecting JavaScript stack in conjunction -with native stack and other runtime environment data. + un-caught exceptions. Useful when inspecting JavaScript stack in conjunction + with native stack and other runtime environment data. * `--report-on-signal` Enables report to be generated upon receiving -the specified (or predefined) signal to the running Node.js process. (See below -on how to modify the signal that triggers the report.) Default signal is `SIGUSR2`. -Useful when a report needs to be triggered from another program. -Application monitors may leverage this feature to collect report at regular -intervals and plot rich set of internal runtime data to their views. + the specified (or predefined) signal to the running Node.js process. (See + below on how to modify the signal that triggers the report.) Default signal is + `SIGUSR2`. Useful when a report needs to be triggered from another program. + Application monitors may leverage this feature to collect report at regular + intervals and plot rich set of internal runtime data to their views. Signal based report generation is not supported in Windows. @@ -413,24 +413,24 @@ signal. However, if `SIGUSR2` is already used for other purposes, then this flag helps to change the signal for report generation and preserve the original meaning of `SIGUSR2` for the said purposes. -* `--report-on-fatalerror` Enables the report to be triggered on -fatal errors (internal errors within the Node.js runtime, such as out of memory) -that leads to termination of the application. Useful to inspect various -diagnostic data elements such as heap, stack, event loop state, resource -consumption etc. to reason about the fatal error. +* `--report-on-fatalerror` Enables the report to be triggered on fatal errors + (internal errors within the Node.js runtime, such as out of memory) + that leads to termination of the application. Useful to inspect various + diagnostic data elements such as heap, stack, event loop state, resource + consumption etc. to reason about the fatal error. * `--report-compact` Write reports in a compact format, single-line JSON, more -easily consumable by log processing systems than the default multi-line format -designed for human consumption. + easily consumable by log processing systems than the default multi-line format + designed for human consumption. * `--report-directory` Location at which the report will be -generated. + generated. * `--report-filename` Name of the file to which the report will be -written. + written. * `--report-signal` Sets or resets the signal for report generation -(not supported on Windows). Default signal is `SIGUSR2`. + (not supported on Windows). Default signal is `SIGUSR2`. A report can also be triggered via an API call from a JavaScript application: diff --git a/doc/api/stream.md b/doc/api/stream.md index a421d4acb6dfa9..81e2a7247ee810 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -682,11 +682,11 @@ A [`Readable`][] stream can be in object mode or not, regardless of whether it is in flowing mode or paused mode. * In flowing mode, data is read from the underlying system automatically -and provided to an application as quickly as possible using events via the -[`EventEmitter`][] interface. + and provided to an application as quickly as possible using events via the + [`EventEmitter`][] interface. * In paused mode, the [`stream.read()`][stream-read] method must be called -explicitly to read chunks of data from the stream. + explicitly to read chunks of data from the stream. All [`Readable`][] streams begin in paused mode but can be switched to flowing mode in one of the following ways: diff --git a/doc/api/string_decoder.md b/doc/api/string_decoder.md index 819283e51175c4..e0e1323cf331e3 100644 --- a/doc/api/string_decoder.md +++ b/doc/api/string_decoder.md @@ -62,7 +62,7 @@ added: v0.9.3 --> * `buffer` {Buffer|TypedArray|DataView} A `Buffer`, or `TypedArray`, or - `DataView` containing the bytes to decode. + `DataView` containing the bytes to decode. * Returns: {string} Returns any remaining input stored in the internal buffer as a string. Bytes @@ -84,7 +84,7 @@ changes: --> * `buffer` {Buffer|TypedArray|DataView} A `Buffer`, or `TypedArray`, or - `DataView` containing the bytes to decode. + `DataView` containing the bytes to decode. * Returns: {string} Returns a decoded string, ensuring that any incomplete multibyte characters at diff --git a/doc/api/tls.md b/doc/api/tls.md index a55847ec3c736d..9a7ea7ee049616 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -644,7 +644,7 @@ added: v0.3.2 --> * `callback` {Function} A listener callback that will be registered to listen -for the server instance's `'close'` event. + for the server instance's `'close'` event. * Returns: {tls.Server} The `server.close()` method stops the server from accepting new connections. @@ -987,8 +987,8 @@ added: v9.9.0 --> * Returns: {Buffer|undefined} The latest `Finished` message that has been -sent to the socket as part of a SSL/TLS handshake, or `undefined` if -no `Finished` message has been sent yet. + sent to the socket as part of a SSL/TLS handshake, or `undefined` if + no `Finished` message has been sent yet. As the `Finished` messages are message digests of the complete handshake (with a total of 192 bits for TLS 1.0 and more for SSL 3.0), they can @@ -1045,7 +1045,7 @@ certificate. `'2A:7A:C2:DD:...'`. * `ext_key_usage` {Array} (Optional) The extended key usage, a set of OIDs. * `subjectaltname` {string} (Optional) A string containing concatenated names - for the subject, an alternative to the `subject` names. + for the subject, an alternative to the `subject` names. * `infoAccess` {Array} (Optional) An array describing the AuthorityInfoAccess, used with OCSP. * `issuerCertificate` {Object} (Optional) The issuer certificate object. For @@ -1111,8 +1111,8 @@ added: v9.9.0 --> * Returns: {Buffer|undefined} The latest `Finished` message that is expected -or has actually been received from the socket as part of a SSL/TLS handshake, -or `undefined` if there is no `Finished` message so far. + or has actually been received from the socket as part of a SSL/TLS handshake, + or `undefined` if there is no `Finished` message so far. As the `Finished` messages are message digests of the complete handshake (with a total of 192 bits for TLS 1.0 and more for SSL 3.0), they can @@ -1167,7 +1167,7 @@ added: v12.11.0 --> * Returns: {Array} List of signature algorithms shared between the server and -the client in the order of decreasing preference. + the client in the order of decreasing preference. See [SSL_get_shared_sigalgs](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_shared_sigalgs.html) @@ -1180,8 +1180,8 @@ added: v13.10.0 * `length` {number} number of bytes to retrieve from keying material * `label` {string} an application specific label, typically this will be a -value from the -[IANA Exporter Label Registry](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels). + value from the + [IANA Exporter Label Registry](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#exporter-labels). * `context` {Buffer} Optionally provide a context. * Returns: {Buffer} requested bytes of the keying material diff --git a/doc/api/util.md b/doc/api/util.md index a0a2ad5567b53d..ab634380c3c406 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -78,7 +78,7 @@ added: v0.11.3 * `section` {string} A string identifying the portion of the application for which the `debuglog` function is being created. * `callback` {Function} A callback invoked the first time the logging function -is called with a function argument that is a more optimized logging function. + is called with a function argument that is a more optimized logging function. * Returns: {Function} The logging function The `util.debuglog()` method is used to create a function that conditionally @@ -1073,7 +1073,7 @@ changes: --> * {symbol} that can be used to declare custom promisified variants of functions, -see [Custom promisified functions][]. + see [Custom promisified functions][]. In addition to being accessible through `util.promisify.custom`, this symbol is [registered globally][global symbol registry] and can be