From a29089d7c866955616c0e363843017e9b9b2a736 Mon Sep 17 00:00:00 2001 From: estrada9166 Date: Mon, 12 Feb 2018 02:31:55 -0500 Subject: [PATCH] doc: add new documentation lint rule Add 80 characters limit to docs. Change docs to fit 80 characters per row. PR-URL: https://github.com/nodejs/node/pull/18726 Fixes: https://github.com/nodejs/node/issues/18703 Reviewed-By: Ruben Bridgewater Reviewed-By: Matteo Collina Reviewed-By: Gibson Fahnestock Reviewed-By: Anatoli Papirovski --- BUILDING.md | 14 +++-- CHANGELOG.md | 2 + COLLABORATOR_GUIDE.md | 30 ++++----- GOVERNANCE.md | 4 +- README.md | 6 +- doc/api/_toc.md | 4 +- doc/api/assert.md | 14 ++--- doc/api/async_hooks.md | 20 +++--- doc/api/buffer.md | 1 + doc/api/child_process.md | 1 + doc/api/cluster.md | 17 ++--- doc/api/console.md | 6 +- doc/api/crypto.md | 13 ++-- doc/api/debugger.md | 7 ++- doc/api/deprecations.md | 21 ++++--- doc/api/dgram.md | 4 +- doc/api/dns.md | 4 +- doc/api/documentation.md | 4 +- doc/api/domain.md | 6 +- doc/api/errors.md | 6 +- doc/api/esm.md | 3 +- doc/api/events.md | 8 +-- doc/api/fs.md | 14 ++--- doc/api/http.md | 63 ++++++++++--------- doc/api/http2.md | 16 ++--- doc/api/https.md | 11 ++-- doc/api/n-api.md | 34 +++++----- doc/api/net.md | 1 + doc/api/process.md | 19 +++--- doc/api/readline.md | 22 ++++--- doc/api/repl.md | 4 +- doc/api/stream.md | 38 ++++++----- doc/api/tls.md | 18 +++--- doc/api/tracing.md | 9 +-- doc/api/util.md | 15 +++-- doc/api/v8.md | 13 ++-- doc/api/vm.md | 12 ++-- doc/changelogs/CHANGELOG_ARCHIVE.md | 1 + doc/changelogs/CHANGELOG_IOJS.md | 1 + doc/changelogs/CHANGELOG_V010.md | 1 + doc/changelogs/CHANGELOG_V012.md | 1 + doc/changelogs/CHANGELOG_V4.md | 1 + doc/changelogs/CHANGELOG_V5.md | 1 + doc/changelogs/CHANGELOG_V6.md | 1 + doc/changelogs/CHANGELOG_V7.md | 1 + doc/changelogs/CHANGELOG_V8.md | 1 + doc/changelogs/CHANGELOG_V9.md | 1 + doc/guides/building-node-with-ninja.md | 6 +- doc/guides/maintaining-V8.md | 14 ++--- doc/guides/maintaining-the-build-files.md | 4 +- doc/guides/writing-and-running-benchmarks.md | 14 +++-- doc/guides/writing-tests.md | 17 ++--- tools/icu/README.md | 39 ++++++++---- tools/remark-preset-lint-node/index.js | 3 +- .../remark-preset-lint-node/package-lock.json | 11 ++++ tools/remark-preset-lint-node/package.json | 1 + 56 files changed, 351 insertions(+), 252 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 74b5903ed22cd0..11378a63b57d0d 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -34,8 +34,8 @@ Support is divided into three tiers: ### Supported platforms The community does not build or test against end-of-life distributions (EoL). -Thus we do not recommend that you use Node on end-of-life or unsupported platforms -in production. +Thus we do not recommend that you use Node on end-of-life or unsupported +platforms in production. | System | Support type | Version | Architectures | Notes | |--------------|--------------|----------------------------------|----------------------|------------------| @@ -107,9 +107,11 @@ installed, you can find them under the menu `Xcode -> Open Developer Tool -> More Developer Tools...`. This step will install `clang`, `clang++`, and `make`. * After building, you may want to setup [firewall rules](tools/macosx-firewall.sh) -to avoid popups asking to accept incoming network connections when running tests: +to avoid popups asking to accept incoming network connections when running +tests: -If the path to your build directory contains a space, the build will likely fail. +If the path to your build directory contains a space, the build will likely +fail. ```console $ sudo ./tools/macosx-firewall.sh @@ -232,8 +234,8 @@ Prerequisites: * **Optional** (to build the MSI): the [WiX Toolset v3.11](http://wixtoolset.org/releases/) and the [Wix Toolset Visual Studio 2017 Extension](https://marketplace.visualstudio.com/items?itemName=RobMensching.WixToolsetVisualStudio2017Extension). -If the path to your build directory contains a space or a non-ASCII character, the -build will likely fail. +If the path to your build directory contains a space or a non-ASCII character, +the build will likely fail. ```console > .\vcbuild diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c4940d44f682e..cdf10f76f5db45 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,7 @@ # Node.js Changelog + + To make the changelog easier to both use and manage, it has been split into multiple files organized according to significant major and minor Node.js release lines. diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 95ef0653552c1e..16dff4d3f561f3 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -154,22 +154,23 @@ The pull request should have a CI status indicator if possible. #### Useful CI Jobs * [`node-test-pull-request`](https://ci.nodejs.org/job/node-test-pull-request/) -is the standard CI run we do to check Pull Requests. It triggers `node-test-commit`, -which runs the `build-ci` and `test-ci` targets on all supported platforms. +is the standard CI run we do to check Pull Requests. It triggers +`node-test-commit`, which runs the `build-ci` and `test-ci` targets on all +supported platforms. * [`node-test-linter`](https://ci.nodejs.org/job/node-test-linter/) -only runs the linter targets, which is useful for changes that only affect comments -or documentation. +only runs the linter targets, which is useful for changes that only affect +comments or documentation. * [`node-test-pull-request-lite`](https://ci.nodejs.org/job/node-test-pull-request-lite/) -only runs the linter job, as well as the tests on LinuxONE. Should only be used for -trivial changes that do not require being tested on all platforms. +only runs the linter job, as well as the tests on LinuxONE. Should only be used +for trivial changes that do not require being tested on all platforms. * [`citgm-smoker`](https://ci.nodejs.org/job/citgm-smoker/) -uses [`CitGM`](https://github.com/nodejs/citgm) to allow you to run `npm install && npm test` -on a large selection of common modules. This is useful to check whether a -change will cause breakage in the ecosystem. To test Node.js ABI changes -you can run [`citgm-abi-smoker`](https://ci.nodejs.org/job/citgm-abi-smoker/). +uses [`CitGM`](https://github.com/nodejs/citgm) to allow you to run +`npm install && npm test` on a large selection of common modules. This is +useful to check whether a change will cause breakage in the ecosystem. To test +Node.js ABI changes you can run [`citgm-abi-smoker`](https://ci.nodejs.org/job/citgm-abi-smoker/). * [`node-stress-single-test`](https://ci.nodejs.org/job/node-stress-single-test/) is designed to allow one to run a group of tests over and over on a specific @@ -483,8 +484,8 @@ Apply external patches: $ curl -L https://github.com/nodejs/node/pull/xxx.patch | git am --whitespace=fix ``` -If the merge fails even though recent CI runs were successful, then a 3-way merge may -be required. In this case try: +If the merge fails even though recent CI runs were successful, then a 3-way +merge may be required. In this case try: ```text $ git am --abort @@ -492,8 +493,9 @@ $ curl -L https://github.com/nodejs/node/pull/xxx.patch | git am -3 --whitespace ``` If the 3-way merge succeeds you can proceed, but make sure to check the changes against the original PR carefully and build/test on at least one platform -before landing. If the 3-way merge fails, then it is most likely that a conflicting -PR has landed since the CI run and you will have to ask the author to rebase. +before landing. If the 3-way merge fails, then it is most likely that a +conflicting PR has landed since the CI run and you will have to ask the author +to rebase. Check and re-review the changes: diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 23c1ac8bb5106e..83d4d9b50a7abe 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -159,9 +159,9 @@ repository, with a summary of the nominee's contributions, for example: * Participation in other projects, teams, and working groups of the Node.js organization * Can be shown using the links - `https://github.com/search?q=author%3A${GITHUB_ID}++org%3Anodejs&type=Issues` + `https://github.com/search?q=author%3A${GITHUB_ID}++org%3Anodejs&type=Issues` and - `https://github.com/search?q=commenter%3A${GITHUB_ID}++org%3Anodejs&type=Issues` +`https://github.com/search?q=commenter%3A${GITHUB_ID}++org%3Anodejs&type=Issues` * Other participation in the wider Node.js community Mention @nodejs/collaborators in the issue to notify other Collaborators about diff --git a/README.md b/README.md index 9dda47e821fc68..aef172b3f24070 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@

- Node.js + Node.js

diff --git a/doc/api/_toc.md b/doc/api/_toc.md index 420fb362fa537a..69f89af5abb394 100644 --- a/doc/api/_toc.md +++ b/doc/api/_toc.md @@ -1,5 +1,5 @@ -@// NB(chrisdickinson): if you move this file, be sure to update tools/doc/html.js to -@// point at the new location. +@// NB(chrisdickinson): if you move this file, be sure to update +@// tools/doc/html.js to point at the new location. * [About these Docs](documentation.html) * [Usage & Example](synopsis.html) diff --git a/doc/api/assert.md b/doc/api/assert.md index cedbc14d427b9a..5ca1f0830853b8 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -25,9 +25,9 @@ changes: description: Added strict mode to the assert module. --> -When using the `strict mode`, any `assert` function will use the equality used in -the strict function mode. So [`assert.deepEqual()`][] will, for example, work the -same as [`assert.deepStrictEqual()`][]. +When using the `strict mode`, any `assert` function will use the equality used +in the strict function mode. So [`assert.deepEqual()`][] will, for example, +work the same as [`assert.deepStrictEqual()`][]. On top of that, error messages which involve objects produce an error diff instead of displaying both objects. That is not the case for the legacy mode. @@ -209,8 +209,8 @@ changes: - version: v9.0.0 pr-url: https://github.com/nodejs/node/pull/15036 description: NaN is now compared using the - [SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero) - comparison. + [SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero) + comparison. - version: v8.5.0 pr-url: https://github.com/nodejs/node/pull/15001 description: Error names and messages are now properly compared @@ -621,8 +621,8 @@ changes: - version: v9.0.0 pr-url: https://github.com/nodejs/node/pull/15036 description: NaN is now compared using the - [SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero) - comparison. + [SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero) + comparison. - version: v9.0.0 pr-url: https://github.com/nodejs/node/pull/15001 description: Error names and messages are now properly compared diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md index 904c32acdc60a3..ff7b794a3093a4 100644 --- a/doc/api/async_hooks.md +++ b/doc/api/async_hooks.md @@ -206,8 +206,8 @@ instance is destroyed. * `type` {string} The type of the async resource. * `triggerAsyncId` {number} The unique ID of the async resource in whose execution context this async resource was created. -* `resource` {Object} Reference to the resource representing the async operation, - needs to be released during _destroy_. +* `resource` {Object} Reference to the resource representing the async + operation, needs to be released during _destroy_. Called when a class is constructed that has the _possibility_ to emit an asynchronous event. This _does not_ mean the instance must call @@ -283,11 +283,11 @@ The `TCPSERVERWRAP` is the server which receives the connections. The `TCPWRAP` is the new connection from the client. When a new connection is made the `TCPWrap` instance is immediately constructed. This -happens outside of any JavaScript stack (side note: a `executionAsyncId()` of `0` -means it's being executed from C++, with no JavaScript stack above it). +happens outside of any JavaScript stack (side note: a `executionAsyncId()` of +`0` means it's being executed from C++, with no JavaScript stack above it). With only that information, it would be impossible to link resources together in -terms of what caused them to be created, so `triggerAsyncId` is given the task of -propagating what resource is responsible for the new resource's existence. +terms of what caused them to be created, so `triggerAsyncId` is given the task +of propagating what resource is responsible for the new resource's existence. ###### `resource` @@ -582,8 +582,8 @@ the details of the V8 [PromiseHooks][] API. ## JavaScript Embedder API Library developers that handle their own asynchronous resources performing tasks -like I/O, connection pooling, or managing callback queues may use the `AsyncWrap` -JavaScript API so that all the appropriate callbacks are called. +like I/O, connection pooling, or managing callback queues may use the +`AsyncWrap` JavaScript API so that all the appropriate callbacks are called. ### `class AsyncResource()` @@ -734,8 +734,8 @@ never be called. #### `asyncResource.triggerAsyncId()` -* Returns: {number} The same `triggerAsyncId` that is passed to the `AsyncResource` -constructor. +* Returns: {number} The same `triggerAsyncId` that is passed to the +`AsyncResource` constructor. [`after` callback]: #async_hooks_after_asyncid [`asyncResource.runInAsyncScope()`]: #async_hooks_asyncresource_runinasyncscope_fn_thisarg_args diff --git a/doc/api/buffer.md b/doc/api/buffer.md index e1911d67146737..225726316aa81c 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -1,6 +1,7 @@ # Buffer + > Stability: 2 - Stable diff --git a/doc/api/child_process.md b/doc/api/child_process.md index ac794e6a23fe63..57a0f9296a46d9 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -1,6 +1,7 @@ # Child Process + > Stability: 2 - Stable diff --git a/doc/api/cluster.md b/doc/api/cluster.md index 11be4d34d5bed8..08a669e4fa0f1f 100644 --- a/doc/api/cluster.md +++ b/doc/api/cluster.md @@ -269,8 +269,8 @@ changes: * Returns: {cluster.Worker} A reference to `worker`. -In a worker, this function will close all servers, wait for the `'close'` event on -those servers, and then disconnect the IPC channel. +In a worker, this function will close all servers, wait for the `'close'` event +on those servers, and then disconnect the IPC channel. In the master, an internal message is sent to the worker causing it to call `.disconnect()` on itself. @@ -280,8 +280,8 @@ Causes `.exitedAfterDisconnect` to be set. Note that after a server is closed, it will no longer accept new connections, but connections may be accepted by any other listening worker. Existing connections will be allowed to close as usual. When no more connections exist, -see [`server.close()`][], the IPC channel to the worker will close allowing it to -die gracefully. +see [`server.close()`][], the IPC channel to the worker will close allowing it +to die gracefully. The above applies *only* to server connections, client connections are not automatically closed by workers, and disconnect does not wait for them to close @@ -465,9 +465,9 @@ Emitted after the worker IPC channel has disconnected. This can occur when a worker exits gracefully, is killed, or is disconnected manually (such as with worker.disconnect()). -There may be a delay between the `'disconnect'` and `'exit'` events. These events -can be used to detect if the process is stuck in a cleanup or if there are -long-living connections. +There may be a delay between the `'disconnect'` and `'exit'` events. These +events can be used to detect if the process is stuck in a cleanup or if there +are long-living connections. ```js cluster.on('disconnect', (worker) => { @@ -639,7 +639,8 @@ Calls `.disconnect()` on each worker in `cluster.workers`. When they are disconnected all internal handles will be closed, allowing the master process to die gracefully if no other event is waiting. -The method takes an optional callback argument which will be called when finished. +The method takes an optional callback argument which will be called when +finished. This can only be called from the master process. diff --git a/doc/api/console.md b/doc/api/console.md index 473c37ea04f30a..1bd595f4b97916 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -411,7 +411,8 @@ added: v8.0.0 * `label` {string} Defaults to `'default'`. This method does not display anything unless used in the inspector. The -`console.markTimeline()` method is the deprecated form of [`console.timeStamp()`][]. +`console.markTimeline()` method is the deprecated form of +[`console.timeStamp()`][]. ### console.profile([label]) -Property for checking and controlling whether a FIPS compliant crypto provider is -currently in use. Setting to true requires a FIPS build of Node.js. +Property for checking and controlling whether a FIPS compliant crypto provider +is currently in use. Setting to true requires a FIPS build of Node.js. This property is deprecated. Please use `crypto.setFips()` and `crypto.getFips()` instead. @@ -1301,7 +1301,8 @@ changes: - `options` {Object} [`stream.transform` options][] Creates and returns a `Cipher` object, with the given `algorithm`, `key` and -initialization vector (`iv`). Optional `options` argument controls stream behavior. +initialization vector (`iv`). Optional `options` argument controls stream +behavior. The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On recent OpenSSL releases, `openssl list-cipher-algorithms` will display the @@ -1397,7 +1398,8 @@ changes: --> - `prime` {string | Buffer | TypedArray | DataView} - `primeEncoding` {string} -- `generator` {number | string | Buffer | TypedArray | DataView} Defaults to `2`. +- `generator` {number | string | Buffer | TypedArray | DataView} Defaults to + `2`. - `generatorEncoding` {string} Creates a `DiffieHellman` key exchange object using the supplied `prime` and an @@ -1420,7 +1422,8 @@ otherwise a number, [`Buffer`][], `TypedArray`, or `DataView` is expected. added: v0.5.0 --> - `primeLength` {number} -- `generator` {number | string | Buffer | TypedArray | DataView} Defaults to `2`. +- `generator` {number | string | Buffer | TypedArray | DataView} Defaults to + `2`. Creates a `DiffieHellman` key exchange object and generates a prime of `primeLength` bits using an optional specific numeric `generator`. diff --git a/doc/api/debugger.md b/doc/api/debugger.md index b0da263f5947b4..00dda306d09232 100644 --- a/doc/api/debugger.md +++ b/doc/api/debugger.md @@ -8,8 +8,8 @@ Node.js includes an out-of-process debugging utility accessible via a [V8 Inspector][] and built-in debugging client. To use it, start Node.js -with the `inspect` argument followed by the path to the script to debug; a prompt -will be displayed indicating successful launch of the debugger: +with the `inspect` argument followed by the path to the script to debug; a +prompt will be displayed indicating successful launch of the debugger: ```txt $ node inspect myscript.js @@ -173,7 +173,8 @@ breakpoint) ### V8 Inspector Integration for Node.js V8 Inspector integration allows attaching Chrome DevTools to Node.js -instances for debugging and profiling. It uses the [Chrome Debugging Protocol][]. +instances for debugging and profiling. It uses the +[Chrome Debugging Protocol][]. V8 Inspector can be enabled by passing the `--inspect` flag when starting a Node.js application. It is also possible to supply a custom port with that flag, diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index cf1e97397ab625..0259bd4625cee1 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -82,16 +82,16 @@ is strongly recommended: * [`Buffer.alloc(size[, fill[, encoding]])`][alloc] - Create a `Buffer` with *initialized* memory. -* [`Buffer.allocUnsafe(size)`][alloc_unsafe_size] - Create a `Buffer` with *uninitialized* - memory. +* [`Buffer.allocUnsafe(size)`][alloc_unsafe_size] - Create a `Buffer` with + *uninitialized* memory. * [`Buffer.allocUnsafeSlow(size)`][] - Create a `Buffer` with *uninitialized* memory. * [`Buffer.from(array)`][] - Create a `Buffer` with a copy of `array` -* [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][from_arraybuffer] - Create a `Buffer` - that wraps the given `arrayBuffer`. +* [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][from_arraybuffer] - + Create a `Buffer` that wraps the given `arrayBuffer`. * [`Buffer.from(buffer)`][] - Create a `Buffer` that copies `buffer`. -* [`Buffer.from(string[, encoding])`][from_string_encoding] - Create a `Buffer` that copies - `string`. +* [`Buffer.from(string[, encoding])`][from_string_encoding] - Create a `Buffer` + that copies `string`. ### DEP0006: child\_process options.customFds @@ -699,7 +699,8 @@ Type: Runtime `Module._debug()` has been deprecated. -The `Module._debug()` function was never documented as an officially supported API. +The `Module._debug()` function was never documented as an officially +supported API. ### DEP0078: REPLServer.turnOffEditorMode() @@ -863,14 +864,16 @@ to one of the other assert methods. Type: Runtime -`timers.enroll()` is deprecated. Please use the publicly documented [`setTimeout()`][] or [`setInterval()`][] instead. +`timers.enroll()` is deprecated. Please use the publicly documented +[`setTimeout()`][] or [`setInterval()`][] instead. ### DEP0096: timers.unenroll() Type: Runtime -`timers.unenroll()` is deprecated. Please use the publicly documented [`clearTimeout()`][] or [`clearInterval()`][] instead. +`timers.unenroll()` is deprecated. Please use the publicly documented +[`clearTimeout()`][] or [`clearInterval()`][] instead. ### DEP0097: MakeCallback with domain property diff --git a/doc/api/dgram.md b/doc/api/dgram.md index e44bf3eea5a166..9209b83a120247 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -394,8 +394,8 @@ added: v8.6.0 *Note: All references to scope in this section are referring to [IPv6 Zone Indices][], which are defined by [RFC 4007][]. In string form, an IP -with a scope index is written as `'IP%scope'` where scope is an interface name or -interface number.* +with a scope index is written as `'IP%scope'` where scope is an interface name +or interface number.* Sets the default outgoing multicast interface of the socket to a chosen interface or back to system interface selection. The `multicastInterface` must diff --git a/doc/api/dns.md b/doc/api/dns.md index cda4823e3ce0e7..fa7c34f654d011 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -143,8 +143,8 @@ changes: - `verbatim` {boolean} When `true`, the callback receives IPv4 and IPv6 addresses in the order the DNS resolver returned them. When `false`, IPv4 addresses are placed before IPv6 addresses. - **Default:** currently `false` (addresses are reordered) but this is expected - to change in the not too distant future. + **Default:** currently `false` (addresses are reordered) but this is + expected to change in the not too distant future. New code should use `{ verbatim: true }`. - `callback` {Function} - `err` {Error} diff --git a/doc/api/documentation.md b/doc/api/documentation.md index c2413d33db8ae4..a864771f446dd9 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -85,8 +85,8 @@ like [`fs.open()`][], will document that. The docs link to the corresponding man pages (short for manual pages) which describe how the syscalls work. Some syscalls, like lchown(2), are BSD-specific. That means, for -example, that [`fs.lchown()`][] only works on macOS and other BSD-derived systems, -and is not available on Linux. +example, that [`fs.lchown()`][] only works on macOS and other BSD-derived +systems, and is not available on Linux. Most Unix syscalls have Windows equivalents, but behavior may differ on Windows relative to Linux and macOS. For an example of the subtle ways in which it's diff --git a/doc/api/domain.md b/doc/api/domain.md index b303b0fdeb1746..a9ca7f2d277be0 100644 --- a/doc/api/domain.md +++ b/doc/api/domain.md @@ -337,9 +337,9 @@ d.on('error', (er) => { The `enter` method is plumbing used by the `run`, `bind`, and `intercept` methods to set the active domain. It sets `domain.active` and `process.domain` to the domain, and implicitly pushes the domain onto the domain stack managed -by the domain module (see [`domain.exit()`][] for details on the domain stack). The -call to `enter` delimits the beginning of a chain of asynchronous calls and I/O -operations bound to a domain. +by the domain module (see [`domain.exit()`][] for details on the domain stack). +The call to `enter` delimits the beginning of a chain of asynchronous calls and +I/O operations bound to a domain. Calling `enter` changes only the active domain, and does not alter the domain itself. `enter` and `exit` can be called an arbitrary number of times on a diff --git a/doc/api/errors.md b/doc/api/errors.md index c2475df1eb7399..b9c52ad0d9af89 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -227,7 +227,8 @@ Error.captureStackTrace(myObject); myObject.stack; // similar to `new Error().stack` ``` -The first line of the trace will be prefixed with `${myObject.name}: ${myObject.message}`. +The first line of the trace will be prefixed with +`${myObject.name}: ${myObject.message}`. The optional `constructorOpt` argument accepts a function. If given, all frames above `constructorOpt`, including `constructorOpt`, will be omitted from the @@ -1321,7 +1322,8 @@ An attempt was made to `require()` an [ES6 module][]. ### ERR_SCRIPT_EXECUTION_INTERRUPTED -Script execution was interrupted by `SIGINT` (For example, when Ctrl+C was pressed). +Script execution was interrupted by `SIGINT` (For example, when Ctrl+C was +pressed). ### ERR_SERVER_ALREADY_LISTEN diff --git a/doc/api/esm.md b/doc/api/esm.md index 2a564332951fea..adde6a199fd068 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -130,7 +130,8 @@ export async function resolve(specifier, } ``` -The parentURL is provided as `undefined` when performing main Node.js load itself. +The parentURL is provided as `undefined` when performing main Node.js load +itself. The default Node.js ES module resolution function is provided as a third argument to the resolver for easy compatibility workflows. diff --git a/doc/api/events.md b/doc/api/events.md index 7b510fac0505c0..afea4f443c9798 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -515,10 +515,10 @@ listener array for the specified `eventName`, then `removeListener` must be called multiple times to remove each instance. Note that once an event has been emitted, all listeners attached to it at the -time of emitting will be called in order. This implies that any `removeListener()` -or `removeAllListeners()` calls *after* emitting and *before* the last listener -finishes execution will not remove them from `emit()` in progress. Subsequent -events will behave as expected. +time of emitting will be called in order. This implies that any +`removeListener()` or `removeAllListeners()` calls *after* emitting and +*before* the last listener finishes execution will not remove them from +`emit()` in progress. Subsequent events will behave as expected. ```js const myEmitter = new MyEmitter(); diff --git a/doc/api/fs.md b/doc/api/fs.md index 5062f76ff134aa..27650c42cd384d 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -2888,9 +2888,9 @@ directory. The returned object is a [`fs.FSWatcher`][]. The second argument is optional. If `options` is provided as a string, it specifies the `encoding`. Otherwise `options` should be passed as an object. -The listener callback gets two arguments `(eventType, filename)`. `eventType` is either -`'rename'` or `'change'`, and `filename` is the name of the file which triggered -the event. +The listener callback gets two arguments `(eventType, filename)`. `eventType` +is either `'rename'` or `'change'`, and `filename` is the name of the file +which triggered the event. Note that on most platforms, `'rename'` is emitted whenever a filename appears or disappears in the directory. @@ -3367,8 +3367,8 @@ and the file position will be updated. If `position` is an integer, the file position will remain unchanged. Following successful read, the `Promise` is resolved with an object with a -`bytesRead` property specifying the number of bytes read, and a `buffer` property -that is a reference to the passed in `buffer` argument. +`bytesRead` property specifying the number of bytes read, and a `buffer` +property that is a reference to the passed in `buffer` argument. #### filehandle.readFile(options) * `options` {Object} A set of options providing information for name generation - * `host` {string} A domain name or IP address of the server to issue the request to + * `host` {string} A domain name or IP address of the server to issue the + request to * `port` {number} Port of remote server * `localAddress` {string} Local interface to bind for network connections when issuing the request @@ -330,9 +331,9 @@ added: v0.7.0 * `socket` {net.Socket} * `head` {Buffer} -Emitted each time a server responds to a request with a `CONNECT` method. If this -event is not being listened for, clients receiving a `CONNECT` method will have -their connections closed. +Emitted each time a server responds to a request with a `CONNECT` method. If +this event is not being listened for, clients receiving a `CONNECT` method will +have their connections closed. A client and server pair demonstrating how to listen for the `'connect'` event: @@ -659,7 +660,8 @@ added: v0.5.9 --> * `timeout` {number} Milliseconds before a request times out. -* `callback` {Function} Optional function to be called when a timeout occurs. Same as binding to the `timeout` event. +* `callback` {Function} Optional function to be called when a timeout occurs. + Same as binding to the `timeout` event. Once a socket is assigned to this request and is connected [`socket.setTimeout()`][] will be called. @@ -726,7 +728,8 @@ buffer. Returns `false` if all or part of the data was queued in user memory. added: v0.1.17 --> -This class inherits from [`net.Server`][] and has the following additional events: +This class inherits from [`net.Server`][] and has the following additional +events: ### Event: 'checkContinue' Sends a HTTP/1.1 100 Continue message to the client, indicating that -the request body should be sent. See the [`'checkContinue'`][] event on `Server`. +the request body should be sent. See the [`'checkContinue'`][] event on +`Server`. ### response.writeHead(statusCode[, statusMessage][, headers]) -An [`Agent`][] object for HTTPS similar to [`http.Agent`][]. See [`https.request()`][] -for more information. +An [`Agent`][] object for HTTPS similar to [`http.Agent`][]. See +[`https.request()`][] for more information. ## Class: https.Server -- `options` {Object | string | URL} Accepts all `options` from [`http.request()`][], - with some differences in default values: +- `options` {Object | string | URL} Accepts all `options` from + [`http.request()`][], with some differences in default values: - `protocol` Defaults to `https:` - `port` Defaults to `443`. - `agent` Defaults to `https.globalAgent`. @@ -251,7 +251,8 @@ const req = https.request(options, (res) => { }); ``` -Example pinning on certificate fingerprint, or the public key (similar to `pin-sha256`): +Example pinning on certificate fingerprint, or the public key (similar to +`pin-sha256`): ```js const tls = require('tls'); diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 8da4c3e2d5462a..ff470acfe1682d 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -139,9 +139,9 @@ create a scope before invoking any functions that can result in the creation of JavaScript values. Handle scopes are created using [`napi_open_handle_scope`][] and are destroyed -using [`napi_close_handle_scope`][]. Closing the scope can indicate to the GC that -all `napi_value`s created during the lifetime of the handle scope are no longer -referenced from the current stack frame. +using [`napi_close_handle_scope`][]. Closing the scope can indicate to the GC +that all `napi_value`s created during the lifetime of the handle scope are no +longer referenced from the current stack frame. For more details, review the [Object Lifetime Management][]. @@ -646,7 +646,8 @@ current scope and the lifespan of the handle changes from the current scope to that of the outer scope. The methods available to open/close escapable scopes are -[`napi_open_escapable_handle_scope`][] and [`napi_close_escapable_handle_scope`][]. +[`napi_open_escapable_handle_scope`][] and +[`napi_close_escapable_handle_scope`][]. The request to promote a handle is made through [`napi_escape_handle`][] which can only be called once. @@ -1342,8 +1343,8 @@ TypedArray objects provide an array-like view over an underlying data buffer where each element has the same underlying binary scalar datatype. It's required that (length * size_of_element) + byte_offset should -be <= the size in bytes of the array passed in. If not, a RangeError exception is -raised. +be <= the size in bytes of the array passed in. If not, a RangeError exception +is raised. JavaScript TypedArray Objects are described in [Section 22.2][] of the ECMAScript Language Specification. @@ -1588,10 +1589,11 @@ its length. *WARNING*: Use caution while using this API. The lifetime of the underlying data buffer is managed by the ArrayBuffer even after it's returned. A -possible safe way to use this API is in conjunction with [`napi_create_reference`][], -which can be used to guarantee control over the lifetime of the -ArrayBuffer. It's also safe to use the returned data buffer within the same -callback as long as there are no calls to other APIs that might trigger a GC. +possible safe way to use this API is in conjunction with +[`napi_create_reference`][], which can be used to guarantee control over the +lifetime of the ArrayBuffer. It's also safe to use the returned data buffer +within the same callback as long as there are no calls to other APIs that might +trigger a GC. #### napi_get_buffer_info + > Stability: 2 - Stable diff --git a/doc/api/process.md b/doc/api/process.md index 8209a07d72853a..6015bb2cc414be 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -193,9 +193,10 @@ of allocated resources (e.g. file descriptors, handles, etc) before shutting down the process. **It is not safe to resume normal operation after `'uncaughtException'`.** -To restart a crashed application in a more reliable way, whether `uncaughtException` -is emitted or not, an external monitor should be employed in a separate process -to detect application failures and recover or restart as needed. +To restart a crashed application in a more reliable way, whether +`uncaughtException` is emitted or not, an external monitor should be employed +in a separate process to detect application failures and recover or restart as +needed. ### Event: 'unhandledRejection' * `options` {Object} - * `input` {stream.Readable} The [Readable][] stream to listen to. This option is - *required*. - * `output` {stream.Writable} The [Writable][] stream to write readline data to. + * `input` {stream.Readable} The [Readable][] stream to listen to. This option + is *required*. + * `output` {stream.Writable} The [Writable][] stream to write readline data + to. * `completer` {Function} An optional function used for Tab autocompletion. * `terminal` {boolean} `true` if the `input` and `output` streams should be treated like a TTY, and have ANSI/VT100 escape codes written to it. Defaults to checking `isTTY` on the `output` stream upon instantiation. * `historySize` {number} Maximum number of history lines retained. To disable - the history set this value to `0`. This option makes sense only if `terminal` - is set to `true` by the user or by an internal `output` check, otherwise the - history caching mechanism is not initialized at all. **Default:** `30` + the history set this value to `0`. This option makes sense only if + `terminal` is set to `true` by the user or by an internal `output` check, + otherwise the history caching mechanism is not initialized at all. + **Default:** `30` * `prompt` {string} The prompt string to use. **Default:** `'> '` * `crlfDelay` {number} If the delay between `\r` and `\n` exceeds `crlfDelay` milliseconds, both `\r` and `\n` will be treated as separate - end-of-line input. `crlfDelay` will be coerced to a number no less than `100`. - It can be set to `Infinity`, in which case `\r` followed by `\n` will always be - considered a single newline (which may be reasonable for [reading files][] - with `\r\n` line delimiter). **Default:** `100` + end-of-line input. `crlfDelay` will be coerced to a number no less than + `100`. It can be set to `Infinity`, in which case `\r` followed by `\n` + will always be considered a single newline (which may be reasonable for + [reading files][] with `\r\n` line delimiter). **Default:** `100` * `removeHistoryDuplicates` {boolean} If `true`, when a new input line added to the history list duplicates an older one, this removes the older line from the list. **Default:** `false` diff --git a/doc/api/repl.md b/doc/api/repl.md index 916d6bd0e28818..873e7449f53065 100644 --- a/doc/api/repl.md +++ b/doc/api/repl.md @@ -412,8 +412,8 @@ changes: * `options` {Object|string} * `prompt` {string} The input prompt to display. Defaults to `> ` (with a trailing space). - * `input` {stream.Readable} The Readable stream from which REPL input will be read. - Defaults to `process.stdin`. + * `input` {stream.Readable} The Readable stream from which REPL input will be + read. Defaults to `process.stdin`. * `output` {stream.Writable} The Writable stream to which REPL output will be written. Defaults to `process.stdout`. * `terminal` {boolean} If `true`, specifies that the `output` should be diff --git a/doc/api/stream.md b/doc/api/stream.md index 85afb631aed175..4cb9907202a3fe 100644 --- a/doc/api/stream.md +++ b/doc/api/stream.md @@ -424,8 +424,8 @@ stream.write('data '); process.nextTick(() => stream.uncork()); ``` -If the [`writable.cork()`][] method is called multiple times on a stream, the same -number of calls to `writable.uncork()` must be called to flush the buffered +If the [`writable.cork()`][] method is called multiple times on a stream, the +same number of calls to `writable.uncork()` must be called to flush the buffered data. ```js @@ -620,8 +620,8 @@ possible states: When `readable.readableFlowing` is `null`, no mechanism for consuming the streams data is provided so the stream will not generate its data. While in this -state, attaching a listener for the `'data'` event, calling the `readable.pipe()` -method, or calling the `readable.resume()` method will switch +state, attaching a listener for the `'data'` event, calling the +`readable.pipe()` method, or calling the `readable.resume()` method will switch `readable.readableFlowing` to `true`, causing the Readable to begin actively emitting events as data is generated. @@ -1193,8 +1193,9 @@ async function print(readable) { print(fs.createReadStream('file')).catch(console.log); ``` -If the loop terminates with a `break` or a `throw`, the stream will be destroyed. -In other terms, iterating over a stream will consume the stream fully. +If the loop terminates with a `break` or a `throw`, the stream will be +destroyed. In other terms, iterating over a stream will consume the stream +fully. ### Duplex and Transform Streams @@ -1305,8 +1306,11 @@ on the type of stream being created, as detailed in the chart below:

[Writable](#stream_class_stream_writable)

-

[_write][stream-_write], [_writev][stream-_writev], - [_final][stream-_final]

+

+ [_write][stream-_write], + [_writev][stream-_writev], + [_final][stream-_final] +

@@ -1317,8 +1321,11 @@ on the type of stream being created, as detailed in the chart below:

[Duplex](#stream_class_stream_duplex)

-

[_read][stream-_read], [_write][stream-_write], [_writev][stream-_writev], - [_final][stream-_final]

+

+ [_read][stream-_read], + [_write][stream-_write], + [_writev][stream-_writev], + [_final][stream-_final]

@@ -1329,8 +1336,11 @@ on the type of stream being created, as detailed in the chart below:

[Transform](#stream_class_stream_transform)

-

[_transform][stream-_transform], [_flush][stream-_flush], - [_final][stream-_final]

+

+ [_transform][stream-_transform], + [_flush][stream-_flush], + [_final][stream-_final] +

@@ -1636,8 +1646,8 @@ constructor and implement the `readable._read()` method. a single value instead of a Buffer of size n. Defaults to `false` * `read` {Function} Implementation for the [`stream._read()`][stream-_read] method. - * `destroy` {Function} Implementation for the [`stream._destroy()`][readable-_destroy] - method. + * `destroy` {Function} Implementation for the + [`stream._destroy()`][readable-_destroy] method. ```js const { Readable } = require('stream'); diff --git a/doc/api/tls.md b/doc/api/tls.md index 5cdab4cbd357cb..0cfab387f20657 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -710,8 +710,8 @@ added: v0.11.8 --> * `options` {Object} - * `rejectUnauthorized` {boolean} If not `false`, the server certificate is verified - against the list of supplied CAs. An `'error'` event is emitted if + * `rejectUnauthorized` {boolean} If not `false`, the server certificate is + verified against the list of supplied CAs. An `'error'` event is emitted if verification fails; `err.code` contains the OpenSSL error code. Defaults to `true`. * `requestCert` @@ -831,8 +831,8 @@ changes: connection/disconnection/destruction of `socket` is the user's responsibility, calling `tls.connect()` will not cause `net.connect()` to be called. - * `rejectUnauthorized` {boolean} If not `false`, the server certificate is verified - against the list of supplied CAs. An `'error'` event is emitted if + * `rejectUnauthorized` {boolean} If not `false`, the server certificate is + verified against the list of supplied CAs. An `'error'` event is emitted if verification fails; `err.code` contains the OpenSSL error code. Defaults to `true`. * `NPNProtocols` {string[]|Buffer[]|Uint8Array[]|Buffer|Uint8Array} @@ -986,7 +986,8 @@ changes: as an array of unencrypted PFX buffers, or an array of objects in the form `{buf: [, passphrase: ]}`. The object form can only occur in an array. `object.passphrase` is optional. Encrypted PFX will be - decrypted with `object.passphrase` if provided, or `options.passphrase` if it is not. + decrypted with `object.passphrase` if provided, or `options.passphrase` if + it is not. * `key` {string|string[]|Buffer|Buffer[]|Object[]} Optional private keys in PEM format. PEM allows the option of private keys being encrypted. Encrypted keys will be decrypted with `options.passphrase`. Multiple keys using @@ -1220,7 +1221,8 @@ added: v0.11.13 --> The default curve name to use for ECDH key agreement in a tls server. The -default value is `'auto'`. See [`tls.createSecureContext()`] for further information. +default value is `'auto'`. See [`tls.createSecureContext()`] for further +information. ## Deprecated APIs @@ -1287,8 +1289,8 @@ changes: opened as a server. * `requestCert` {boolean} `true` to specify whether a server should request a certificate from a connecting client. Only applies when `isServer` is `true`. -* `rejectUnauthorized` {boolean} If not `false` a server automatically reject clients - with invalid certificates. Only applies when `isServer` is `true`. +* `rejectUnauthorized` {boolean} If not `false` a server automatically reject + clients with invalid certificates. Only applies when `isServer` is `true`. * `options` * `secureContext`: An optional TLS context object from [`tls.createSecureContext()`][] diff --git a/doc/api/tracing.md b/doc/api/tracing.md index fbfa2941eff9ed..67b3394d5520e1 100644 --- a/doc/api/tracing.md +++ b/doc/api/tracing.md @@ -5,12 +5,13 @@ Trace Event provides a mechanism to centralize tracing information generated by V8, Node core, and userspace code. -Tracing can be enabled by passing the `--trace-events-enabled` flag when starting a -Node.js application. +Tracing can be enabled by passing the `--trace-events-enabled` flag when +starting a Node.js application. The set of categories for which traces are recorded can be specified using the -`--trace-event-categories` flag followed by a list of comma separated category names. -By default the `node`, `node.async_hooks`, and `v8` categories are enabled. +`--trace-event-categories` flag followed by a list of comma separated category +names. By default the `node`, `node.async_hooks`, and `v8` categories are +enabled. ```txt node --trace-events-enabled --trace-event-categories v8,node,node.async_hooks server.js diff --git a/doc/api/util.md b/doc/api/util.md index dd5620c4808be3..ae4094b73a56a4 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -107,7 +107,8 @@ const debuglog = util.debuglog('foo-bar'); debuglog('hi there, it\'s foo-bar [%d]', 2333); ``` -if it is run with `NODE_DEBUG=foo*` in the environment, then it will output something like: +if it is run with `NODE_DEBUG=foo*` in the environment, then it will output +something like: ```txt FOO-BAR 3257: hi there, it's foo-bar [2333] ``` @@ -206,8 +207,9 @@ corresponding argument. Supported placeholders are: contains circular references. * `%o` - Object. A string representation of an object with generic JavaScript object formatting. - Similar to `util.inspect()` with options `{ showHidden: true, showProxy: true }`. - This will show the full object including non-enumerable properties and proxies. + Similar to `util.inspect()` with options + `{ showHidden: true, showProxy: true }`. This will show the full object + including non-enumerable properties and proxies. * `%O` - Object. A string representation of an object with generic JavaScript object formatting. Similar to `util.inspect()` without options. This will show the full object not including non-enumerable properties and proxies. @@ -400,8 +402,8 @@ The `util.inspect()` method returns a string representation of `object` that is intended for debugging. The output of `util.inspect` may change at any time and should not be depended upon programmatically. Additional `options` may be passed that alter certain aspects of the formatted string. -`util.inspect()` will use the constructor's name and/or `@@toStringTag` to make an -identifiable tag for an inspected value. +`util.inspect()` will use the constructor's name and/or `@@toStringTag` to make +an identifiable tag for an inspected value. ```js class Foo { @@ -702,7 +704,8 @@ console.log(promisified === doSomething[util.promisify.custom]); This can be useful for cases where the original function does not follow the standard format of taking an error-first callback as the last argument. -For example, with a function that takes in `(foo, onSuccessCallback, onErrorCallback)`: +For example, with a function that takes in +`(foo, onSuccessCallback, onErrorCallback)`: ```js doSomething[util.promisify.custom] = (foo) => { diff --git a/doc/api/v8.md b/doc/api/v8.md index ac46e5df585333..f929fe6a03e952 100644 --- a/doc/api/v8.md +++ b/doc/api/v8.md @@ -108,11 +108,11 @@ Returns an object with the following properties: * `peak_malloced_memory` {number} * `does_zap_garbage` {number} -`does_zap_garbage` is a 0/1 boolean, which signifies whether the `--zap_code_space` -option is enabled or not. This makes V8 overwrite heap garbage with a bit -pattern. The RSS footprint (resident memory set) gets bigger because it -continuously touches all heap pages and that makes them less likely to get -swapped out by the operating system. +`does_zap_garbage` is a 0/1 boolean, which signifies whether the +`--zap_code_space` option is enabled or not. This makes V8 overwrite heap +garbage with a bit pattern. The RSS footprint (resident memory set) gets bigger +because it continuously touches all heap pages and that makes them less likely +to get swapped out by the operating system. ```js @@ -299,7 +299,8 @@ added: v8.0.0 #### new Deserializer(buffer) -* `buffer` {Buffer|Uint8Array} A buffer returned by [`serializer.releaseBuffer()`][]. +* `buffer` {Buffer|Uint8Array} A buffer returned by + [`serializer.releaseBuffer()`][]. Creates a new `Deserializer` object. diff --git a/doc/api/vm.md b/doc/api/vm.md index 0a5999b7ffd715..12e35e9f727d3e 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -184,9 +184,9 @@ in the ECMAScript specification. * {any} -If the `module.status` is `'errored'`, this property contains the exception thrown -by the module during evaluation. If the status is anything else, accessing this -property will result in a thrown exception. +If the `module.status` is `'errored'`, this property contains the exception +thrown by the module during evaluation. If the status is anything else, +accessing this property will result in a thrown exception. The value `undefined` cannot be used for cases where there is not a thrown exception due to possible ambiguity with `throw undefined;`. @@ -773,9 +773,9 @@ local scope, so the value `localVar` is changed. In this way ## Example: Running an HTTP Server within a VM -When using either [`script.runInThisContext()`][] or [`vm.runInThisContext()`][], the -code is executed within the current V8 global context. The code passed -to this VM context will have its own isolated scope. +When using either [`script.runInThisContext()`][] or +[`vm.runInThisContext()`][], the code is executed within the current V8 global +context. The code passed to this VM context will have its own isolated scope. In order to run a simple web server using the `http` module the code passed to the context must either call `require('http')` on its own, or have a reference diff --git a/doc/changelogs/CHANGELOG_ARCHIVE.md b/doc/changelogs/CHANGELOG_ARCHIVE.md index 35d879064f0283..fc56c492d9c93f 100644 --- a/doc/changelogs/CHANGELOG_ARCHIVE.md +++ b/doc/changelogs/CHANGELOG_ARCHIVE.md @@ -1,6 +1,7 @@ # Node.js ChangeLog Archive + diff --git a/doc/changelogs/CHANGELOG_IOJS.md b/doc/changelogs/CHANGELOG_IOJS.md index daac573eab7031..a042e50fae1b63 100644 --- a/doc/changelogs/CHANGELOG_IOJS.md +++ b/doc/changelogs/CHANGELOG_IOJS.md @@ -1,6 +1,7 @@ # io.js ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V010.md b/doc/changelogs/CHANGELOG_V010.md index d9ad08acf0f8ba..cdea52193bb331 100644 --- a/doc/changelogs/CHANGELOG_V010.md +++ b/doc/changelogs/CHANGELOG_V010.md @@ -1,6 +1,7 @@ # Node.js 0.10 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V012.md b/doc/changelogs/CHANGELOG_V012.md index a57773269814ee..9ba23c086055d0 100644 --- a/doc/changelogs/CHANGELOG_V012.md +++ b/doc/changelogs/CHANGELOG_V012.md @@ -1,6 +1,7 @@ # Node.js 0.12 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V4.md b/doc/changelogs/CHANGELOG_V4.md index b6cc90113191ea..3257b14dbd6801 100644 --- a/doc/changelogs/CHANGELOG_V4.md +++ b/doc/changelogs/CHANGELOG_V4.md @@ -1,6 +1,7 @@ # Node.js 4 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V5.md b/doc/changelogs/CHANGELOG_V5.md index 4f223e62f79b73..eb8c6e74cad826 100644 --- a/doc/changelogs/CHANGELOG_V5.md +++ b/doc/changelogs/CHANGELOG_V5.md @@ -1,6 +1,7 @@ # Node.js 5 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V6.md b/doc/changelogs/CHANGELOG_V6.md index 0c9343bcadaa85..2a0860e3f45833 100644 --- a/doc/changelogs/CHANGELOG_V6.md +++ b/doc/changelogs/CHANGELOG_V6.md @@ -1,6 +1,7 @@ # Node.js 6 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V7.md b/doc/changelogs/CHANGELOG_V7.md index dd9fa4d269a8d6..dc9c9154b5b2a4 100644 --- a/doc/changelogs/CHANGELOG_V7.md +++ b/doc/changelogs/CHANGELOG_V7.md @@ -1,6 +1,7 @@ # Node.js 7 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V8.md b/doc/changelogs/CHANGELOG_V8.md index 60cd5ca3328197..be816ef0bd28e5 100644 --- a/doc/changelogs/CHANGELOG_V8.md +++ b/doc/changelogs/CHANGELOG_V8.md @@ -1,6 +1,7 @@ # Node.js 8 ChangeLog +
diff --git a/doc/changelogs/CHANGELOG_V9.md b/doc/changelogs/CHANGELOG_V9.md index a95c79634dbee3..84b7a4ce08973a 100644 --- a/doc/changelogs/CHANGELOG_V9.md +++ b/doc/changelogs/CHANGELOG_V9.md @@ -1,6 +1,7 @@ # Node.js 9 ChangeLog +
diff --git a/doc/guides/building-node-with-ninja.md b/doc/guides/building-node-with-ninja.md index 5473d662be2f27..a70d78fd7aac49 100644 --- a/doc/guides/building-node-with-ninja.md +++ b/doc/guides/building-node-with-ninja.md @@ -35,13 +35,15 @@ runner directly, like so: ## Alias -`alias nnode='./configure --ninja && ninja -C out/Release && ln -fs out/Release/node node'` +`alias nnode='./configure --ninja && ninja -C out/Release && ln -fs +out/Release/node node'` ## Producing a debug build The above alias can be modified slightly to produce a debug build, rather than a release build as shown below: -`alias nnodedebug='./configure --ninja && ninja -C out/Debug && ln -fs out/Debug/node node_g'` +`alias nnodedebug='./configure --ninja && ninja -C out/Debug && ln -fs +out/Debug/node node_g'` [Ninja]: https://ninja-build.org/ diff --git a/doc/guides/maintaining-V8.md b/doc/guides/maintaining-V8.md index 04bc155660105b..cdf7f19b3d9ed6 100644 --- a/doc/guides/maintaining-V8.md +++ b/doc/guides/maintaining-V8.md @@ -243,13 +243,13 @@ V8 5.1 (since it was already abandoned). Since Node.js `v6.x` uses V8 5.1, the fix needed to be cherry-picked. To cherry-pick, here's an example workflow: * Download and apply the commit linked-to in the issue (in this case a51f429). - `curl -L https://github.com/v8/v8/commit/a51f429.patch | git am -3 --directory=deps/v8`. - If the branches have diverged significantly, this may not apply cleanly. It - may help to try to cherry-pick the merge to the oldest branch that was done - upstream in V8. In this example, this would be the patch from the merge to - 5.2. The hope is that this would be closer to the V8 5.1, and has a better - chance of applying cleanly. If you're stuck, feel free to ping @ofrobots for - help. + `curl -L https://github.com/v8/v8/commit/a51f429.patch | git am -3 + --directory=deps/v8`. If the branches have diverged significantly, this may + not apply cleanly. It may help to try to cherry-pick the merge to the oldest + branch that was done upstream in V8. In this example, this would be the patch + from the merge to 5.2. The hope is that this would be closer to the V8 5.1, + and has a better chance of applying cleanly. If you're stuck, feel free to + ping @ofrobots for help. * Modify the commit message to match the format we use for V8 backports and replace yourself as the author. `git commit --amend --reset-author`. You may want to add extra description if necessary to indicate the impact of the fix diff --git a/doc/guides/maintaining-the-build-files.md b/doc/guides/maintaining-the-build-files.md index ca5ee090a69dcc..d6e4b0be249c24 100644 --- a/doc/guides/maintaining-the-build-files.md +++ b/doc/guides/maintaining-the-build-files.md @@ -15,8 +15,8 @@ There are three main build files that may be directly run when building Node.js: Makefile mentioned below is maintained separately by humans). For a detailed guide on this script, see [configure](#configure). - `vcbuild.bat`: A Windows Batch Script that locates build tools, provides a - subset of the targets available in the [Makefile](#makefile), and a few targets - of its own. For a detailed guide on this script, see + subset of the targets available in the [Makefile](#makefile), and a few + targets of its own. For a detailed guide on this script, see [vcbuild.bat](#vcbuild.bat). - `Makefile`: A Makefile that can be run with GNU Make. It provides a set of targets that build and test the Node.js binary, produce releases and diff --git a/doc/guides/writing-and-running-benchmarks.md b/doc/guides/writing-and-running-benchmarks.md index 66b5072a4979d7..a6482c607893ca 100644 --- a/doc/guides/writing-and-running-benchmarks.md +++ b/doc/guides/writing-and-running-benchmarks.md @@ -31,8 +31,8 @@ either [`wrk`][wrk] or [`autocannon`][autocannon]. path. In order to compare two HTTP benchmark runs, make sure that the Node.js version in the path is not altered. -`wrk` may be available through one of the available package managers. If not, it can -be easily built [from source][wrk] via `make`. +`wrk` may be available through one of the available package managers. If not, +it can be easily built [from source][wrk] via `make`. By default, `wrk` will be used as the benchmarker. If it is not available, `autocannon` will be used in its place. When creating an HTTP benchmark, the @@ -184,7 +184,9 @@ The `compare.js` tool will then produce a csv file with the benchmark results. $ node benchmark/compare.js --old ./node-master --new ./node-pr-5134 string_decoder > compare-pr-5134.csv ``` -*Tips: there are some useful options of `benchmark/compare.js`. For example, if you want to compare the benchmark of a single script instead of a whole module, you can use the `--filter` option:* +*Tips: there are some useful options of `benchmark/compare.js`. For example, +if you want to compare the benchmark of a single script instead of a whole +module, you can use the `--filter` option:* ```console --new ./new-node-binary new node binary (required) @@ -234,9 +236,9 @@ is less than `0.05`._ The `compare.R` tool can also produce a box plot by using the `--plot filename` option. In this case there are 48 different benchmark combinations, and there may be a need to filter the csv file. This can be done while benchmarking -using the `--set` parameter (e.g. `--set encoding=ascii`) or by filtering results -afterwards using tools such as `sed` or `grep`. In the `sed` case be sure to -keep the first line since that contains the header information. +using the `--set` parameter (e.g. `--set encoding=ascii`) or by filtering +results afterwards using tools such as `sed` or `grep`. In the `sed` case be +sure to keep the first line since that contains the header information. ```console $ cat compare-pr-5134.csv | sed '1p;/encoding=ascii/!d' | Rscript benchmark/compare.R --plot compare-plot.png diff --git a/doc/guides/writing-tests.md b/doc/guides/writing-tests.md index aa4412e1613c2c..28a062d8b79aca 100644 --- a/doc/guides/writing-tests.md +++ b/doc/guides/writing-tests.md @@ -138,15 +138,15 @@ platforms. ### The *common* API -Make use of the helpers from the `common` module as much as possible. Please refer -to the [common file documentation](https://github.com/nodejs/node/tree/master/test/common) +Make use of the helpers from the `common` module as much as possible. Please +refer to the [common file documentation](https://github.com/nodejs/node/tree/master/test/common) for the full details of the helpers. #### common.mustCall -One interesting case is `common.mustCall`. The use of `common.mustCall` may avoid -the use of extra variables and the corresponding assertions. Let's explain this -with a real test from the test suite. +One interesting case is `common.mustCall`. The use of `common.mustCall` may +avoid the use of extra variables and the corresponding assertions. Let's +explain this with a real test from the test suite. ```javascript 'use strict'; @@ -200,9 +200,10 @@ const server = http.createServer(common.mustCall(function(req, res) { ``` #### Countdown Module -The common [Countdown module](https://github.com/nodejs/node/tree/master/test/common#countdown-module) provides a simple countdown mechanism for tests that -require a particular action to be taken after a given number of completed tasks -(for instance, shutting down an HTTP server after a specific number of requests). +The common [Countdown module](https://github.com/nodejs/node/tree/master/test/common#countdown-module) +provides a simple countdown mechanism for tests that require a particular +action to be taken after a given number of completed tasks (for instance, +shutting down an HTTP server after a specific number of requests). ```javascript const Countdown = require('../common/countdown'); diff --git a/tools/icu/README.md b/tools/icu/README.md index e1c753ebf3347e..9b7f72128fc52d 100644 --- a/tools/icu/README.md +++ b/tools/icu/README.md @@ -1,20 +1,29 @@ # Notes about the `tools/icu` subdirectory -This directory contains tools, data, and information about the [http://icu-project.org](ICU) (International Components for Unicode) integration. ICU is used to provide internationalization functionality. - -- `patches/` are one-off patches, actually entire source file replacements, organized by ICU version number. -- `icu_small.json` controls the "small" (English only) ICU. It is input to `icutrim.py` -- `icu-generic.gyp` is the build file used for most ICU builds within ICU. -- `icu-system.gyp` is an alternate build file used when `--with-intl=system-icu` is invoked. It builds against the `pkg-config` located ICU. -- `iculslocs.cc` is source for the `iculslocs` utility, invoked by `icutrim.py` as part of repackaging. Not used separately. See source for more details. +This directory contains tools, data, and information about the [http://icu-project.org](ICU) +(International Components for Unicode) integration. ICU is used to provide +internationalization functionality. + +- `patches/` are one-off patches, actually entire source file replacements, + organized by ICU version number. +- `icu_small.json` controls the "small" (English only) ICU. It is input to + `icutrim.py` +- `icu-generic.gyp` is the build file used for most ICU builds within ICU. + +- `icu-system.gyp` is an alternate build file used when `--with-intl=system-icu` + is invoked. It builds against the `pkg-config` located ICU. +- `iculslocs.cc` is source for the `iculslocs` utility, invoked by `icutrim.py` + as part of repackaging. Not used separately. See source for more details. - `no-op.cc` — empty function to convince gyp to use a C++ compiler. - `README.md` — you are here - `shrink-icu-src.py` — this is used during upgrade (see guide below) ## How to upgrade ICU -- Make sure your node workspace is clean (clean `git status`) should be sufficient. -- Configure Node with the specific [ICU version](http://icu-project.org/download) you want to upgrade to, for example: +- Make sure your node workspace is clean (clean `git status`) should be + sufficient. +- Configure Node with the specific [ICU version](http://icu-project.org/download) + you want to upgrade to, for example: ```shell ./configure \ @@ -26,8 +35,10 @@ make > _Note_ in theory, the equivalent `vcbuild.bat` commands should work also, > but the commands below are makefile-centric. -- If there are ICU version-specific changes needed, you may need to make changes in `icu-generic.gyp` or add patch files to `tools/icu/patches`. - - Specifically, look for the lists in `sources!` in the `icu-generic.gyp` for files to exclude. +- If there are ICU version-specific changes needed, you may need to make changes + in `icu-generic.gyp` or add patch files to `tools/icu/patches`. + - Specifically, look for the lists in `sources!` in the `icu-generic.gyp` for + files to exclude. - Verify the node build works: @@ -95,7 +106,11 @@ make test-ci - commit the change to `configure` along with the updated `LICENSE` file. - - Note: To simplify review, I often will “pre-land” this patch, meaning that I run the patch through `curl -L https://github.com/nodejs/node/pull/xxx.patch | git am -3 --whitespace=fix` per the collaborator’s guide… and then push that patched branch into my PR's branch. This reduces the whitespace changes that show up in the PR, since the final land will eliminate those anyway. + - Note: To simplify review, I often will “pre-land” this patch, meaning that + I run the patch through `curl -L https://github.com/nodejs/node/pull/xxx.patch + | git am -3 --whitespace=fix` per the collaborator’s guide… and then push that + patched branch into my PR's branch. This reduces the whitespace changes that + show up in the PR, since the final land will eliminate those anyway. ----- diff --git a/tools/remark-preset-lint-node/index.js b/tools/remark-preset-lint-node/index.js index a59d5d78d8fff8..d50b30f83dc57e 100644 --- a/tools/remark-preset-lint-node/index.js +++ b/tools/remark-preset-lint-node/index.js @@ -49,5 +49,6 @@ module.exports.plugins = [ ] ], [require('remark-lint-strong-marker'), '*'], - [require('remark-lint-table-cell-padding'), 'padded'] + [require('remark-lint-table-cell-padding'), 'padded'], + [require('remark-lint-maximum-line-length'), 80] ]; diff --git a/tools/remark-preset-lint-node/package-lock.json b/tools/remark-preset-lint-node/package-lock.json index 8c84d7f782b61d..55f29b9aba9e73 100644 --- a/tools/remark-preset-lint-node/package-lock.json +++ b/tools/remark-preset-lint-node/package-lock.json @@ -185,6 +185,17 @@ "unist-util-visit": "1.2.0" } }, + "remark-lint-maximum-line-length": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/remark-lint-maximum-line-length/-/remark-lint-maximum-line-length-1.0.2.tgz", + "integrity": "sha512-M4UIXAAbtLgoQbTDVwdKOEFbTKtJSZ+pCW7ZqMFs+cbIN0Svm32LM9+xpVfVU0hLYt3Ypl++EAPfguBNe1PZEw==", + "requires": { + "unified-lint-rule": "1.0.2", + "unist-util-generated": "1.1.1", + "unist-util-position": "3.0.0", + "unist-util-visit": "1.2.0" + } + }, "remark-lint-no-auto-link-without-protocol": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/remark-lint-no-auto-link-without-protocol/-/remark-lint-no-auto-link-without-protocol-1.0.1.tgz", diff --git a/tools/remark-preset-lint-node/package.json b/tools/remark-preset-lint-node/package.json index beabb75cdb22b6..285ba74d5f88bb 100644 --- a/tools/remark-preset-lint-node/package.json +++ b/tools/remark-preset-lint-node/package.json @@ -32,6 +32,7 @@ "remark-lint-first-heading-level": "^1.0.0", "remark-lint-hard-break-spaces": "^1.0.1", "remark-lint-heading-style": "^1.0.0", + "remark-lint-maximum-line-length": "^1.0.2", "remark-lint-no-auto-link-without-protocol": "^1.0.0", "remark-lint-no-blockquote-without-caret": "^1.0.0", "remark-lint-no-duplicate-definitions": "^1.0.0",