doc: some fixes in repl.md

.eslintrc

@@ -93,6 +93,7 @@ rules:
   no-multiple-empty-lines: [2, {max: 2, maxEOF: 0, maxBOF: 0}]
   no-tabs: 2
   no-trailing-spaces: 2
+  operator-linebreak: [2, after, {overrides: {'?': ignore, ':': ignore}}]
   quotes: [2, single, avoid-escape]
   semi: 2
   semi-spacing: 2

.github/PULL_REQUEST_TEMPLATE.md

@@ -9,7 +9,7 @@ Contributors guide: https://github.com/nodejs/node/blob/master/CONTRIBUTING.md
 ##### Checklist
 <!-- Remove items that do not apply. For completed items, change [ ] to [x]. -->
 
-- [ ] `make -j8 test` (UNIX), or `vcbuild test nosign` (Windows) passes
+- [ ] `make -j4 test` (UNIX), or `vcbuild test nosign` (Windows) passes
 - [ ] tests and/or benchmarks are included
 - [ ] documentation is changed or added
 - [ ] commit message follows commit guidelines

BUILDING.md

@@ -24,16 +24,33 @@ On OS X, you will also need:
     this under the menu `Xcode -> Preferences -> Downloads`
   * This step will install `gcc` and the related toolchain containing `make`
 
+* You may want to setup [firewall rules](tools/macosx-firewall.sh) to avoid
+popups asking to accept incoming network connections when running tests:
+
+```console
+$ sudo ./tools/macosx-firewall.sh
+```
+Running this script will add rules for the executable `node` in the out
+directory and the symbolic `node` link in the projects root directory.
+
 On FreeBSD and OpenBSD, you may also need:
 * libexecinfo
 
 To build Node.js:
 
 ```console
 $ ./configure
-$ make
+$ make -j4
 ```
 
+Running `make` with the `-j4` flag will cause it to run 4 compilation jobs
+concurrently which may significantly reduce build time. The number after `-j`
+can be changed to best suit the number of processor cores on your machine. If
+you run into problems running `make` with concurrency, try running it without
+the `-j4` flag. See the
+[GNU Make Documentation](https://www.gnu.org/software/make/manual/html_node/Parallel.html)
+for more information.
+
 Note that the above requires that `python` resolve to Python 2.6 or 2.7 and not a newer version.
 
 To run the tests:

CONTRIBUTING.md

@@ -156,7 +156,7 @@ to see how they should be structured can also help.
 To run the tests on Unix / OS X:
 
 ```text
-$ ./configure && make -j8 test
+$ ./configure && make -j4 test
 ```
 
 Windows:
@@ -189,7 +189,7 @@ You can run tests directly with node:
 $ ./node ./test/parallel/test-stream2-transform.js
 ```
 
-Remember to recompile with `make -j8` in between test runs if you change
+Remember to recompile with `make -j4` in between test runs if you change
 core modules.
 
 ### Step 6: Push

Makefile

@@ -71,11 +71,11 @@ endif
 # See comments on the build-addons target for some more info
 $(NODE_EXE): config.gypi out/Makefile
 	$(MAKE) -C out BUILDTYPE=Release V=$(V)
-	if [ ! -r $(NODE_EXE) -o ! -L $(NODE_EXE) ]; then ln -fs out/Release/$(NODE_EXE) $@; fi
+	if [ ! -r $@ -o ! -L $@ ]; then ln -fs out/Release/$(NODE_EXE) $@; fi
 
 $(NODE_G_EXE): config.gypi out/Makefile
 	$(MAKE) -C out BUILDTYPE=Debug V=$(V)
-	if [ ! -r $(NODE_EXE) -o ! -L $(node_EXE) ]; then ln -fs out/Debug/$(NODE_EXE) $@; fi
+	if [ ! -r $@ -o ! -L $@ ]; then ln -fs out/Debug/$(NODE_EXE) $@; fi
 
 out/Makefile: common.gypi deps/uv/uv.gyp deps/http_parser/http_parser.gyp \
               deps/zlib/zlib.gyp deps/v8/gypfiles/toolchain.gypi \

README.md

@@ -237,8 +237,8 @@ more information about the governance of the Node.js project, see
 **Ilkka Myller** <ilkka.myller@nodefield.com>
 * [isaacs](https://github.com/isaacs) -
 **Isaac Z. Schlueter** <i@izs.me>
-* [italoacasas](https://github.com/italoacasas)
-**Italo A. Casas**  <me@italoacasas.com>
+* [italoacasas](https://github.com/italoacasas) -
+**Italo A. Casas** <me@italoacasas.com>
 * [iWuzHere](https://github.com/iWuzHere) -
 **Imran Iqbal** <imran@imraniqbal.org>
 * [JacksonTian](https://github.com/JacksonTian) -

doc/api/buffer.md

@@ -392,9 +392,9 @@ deprecated: v6.0.0
 
 * `size` {Integer} The desired length of the new `Buffer`
 
-Allocates a new `Buffer` of `size` bytes.  The `size` must be less than or equal
-to the value of [`buffer.kMaxLength`]. Otherwise, a [`RangeError`] is thrown.
-A zero-length `Buffer` will be created if `size <= 0`.
+Allocates a new `Buffer` of `size` bytes.  If the `size` is larger than
+[`buffer.kMaxLength`] or smaller than 0, a [`RangeError`] will be thrown.
+A zero-length `Buffer` will be created if `size` is 0.
 
 Unlike [`ArrayBuffers`][`ArrayBuffer`], the underlying memory for `Buffer` instances
 created in this way is *not initialized*. The contents of a newly created `Buffer`
@@ -470,9 +470,9 @@ const buf = Buffer.alloc(5);
 console.log(buf);
 ```
 
-The `size` must be less than or equal to the value of [`buffer.kMaxLength`].
-Otherwise, a [`RangeError`] is thrown. A zero-length `Buffer` will be created if
-`size <= 0`.
+Allocates a new `Buffer` of `size` bytes.  If the `size` is larger than
+[`buffer.kMaxLength`] or smaller than 0, a [`RangeError`] will be thrown.
+A zero-length `Buffer` will be created if `size` is 0.
 
 If `fill` is specified, the allocated `Buffer` will be initialized by calling
 [`buf.fill(fill)`][`buf.fill()`].
@@ -511,9 +511,9 @@ added: v5.10.0
 
 * `size` {Integer} The desired length of the new `Buffer`
 
-Allocates a new *non-zero-filled* `Buffer` of `size` bytes. The `size` must
-be less than or equal to the value of [`buffer.kMaxLength`]. Otherwise, a
-[`RangeError`] is thrown. A zero-length `Buffer` will be created if `size <= 0`.
+Allocates a new `Buffer` of `size` bytes.  If the `size` is larger than
+[`buffer.kMaxLength`] or smaller than 0, a [`RangeError`] will be thrown.
+A zero-length `Buffer` will be created if `size` is 0.
 
 The underlying memory for `Buffer` instances created in this way is *not
 initialized*. The contents of the newly created `Buffer` are unknown and
@@ -557,10 +557,9 @@ added: v5.10.0
 
 * `size` {Integer} The desired length of the new `Buffer`
 
-Allocates a new *non-zero-filled* and non-pooled `Buffer` of `size` bytes. The
-`size` must be less than or equal to the value of [`buffer.kMaxLength`].
-Otherwise, a [`RangeError`] is thrown. A zero-length `Buffer` will be created if
-`size <= 0`.
+Allocates a new `Buffer` of `size` bytes.  If the `size` is larger than
+[`buffer.kMaxLength`] or smaller than 0, a [`RangeError`] will be thrown.
+A zero-length `Buffer` will be created if `size` is 0.
 
 The underlying memory for `Buffer` instances created in this way is *not
 initialized*. The contents of the newly created `Buffer` are unknown and
@@ -2390,9 +2389,9 @@ deprecated: v6.0.0
 
 * `size` {Integer} The desired length of the new `SlowBuffer`
 
-Allocates a new `SlowBuffer` of `size` bytes. The `size` must be less than
-or equal to the value of [`buffer.kMaxLength`]. Otherwise, a [`RangeError`] is
-thrown. A zero-length `Buffer` will be created if `size <= 0`.
+Allocates a new `Buffer` of `size` bytes.  If the `size` is larger than
+[`buffer.kMaxLength`] or smaller than 0, a [`RangeError`] will be thrown.
+A zero-length `Buffer` will be created if `size` is 0.
 
 The underlying memory for `SlowBuffer` instances is *not initialized*. The
 contents of a newly created `SlowBuffer` are unknown and could contain

doc/api/child_process.md

@@ -91,11 +91,11 @@ const spawn = require('child_process').spawn;
 const bat = spawn('cmd.exe', ['/c', 'my.bat']);
 
 bat.stdout.on('data', (data) => {
-  console.log(data);
+  console.log(data.toString());
 });
 
 bat.stderr.on('data', (data) => {
-  console.log(data);
+  console.log(data.toString());
 });
 
 bat.on('exit', (code) => {
@@ -113,7 +113,7 @@ exec('my.bat', (err, stdout, stderr) => {
 });
 
 // Script with spaces in the filename:
-const bat = spawn('"my script.cmd"', ['a', 'b'], { shell:true });
+const bat = spawn('"my script.cmd"', ['a', 'b'], { shell: true });
 // or:
 exec('"my script.cmd" a b', (err, stdout, stderr) => {
   // ...
@@ -383,7 +383,7 @@ ps.on('close', (code) => {
 });
 
 grep.stdout.on('data', (data) => {
-  console.log(`${data}`);
+  console.log(data.toString());
 });
 
 grep.stderr.on('data', (data) => {
@@ -467,8 +467,8 @@ const out = fs.openSync('./out.log', 'a');
 const err = fs.openSync('./out.log', 'a');
 
 const child = spawn('prg', [], {
- detached: true,
- stdio: [ 'ignore', out, err ]
+  detached: true,
+  stdio: [ 'ignore', out, err ]
 });
 
 child.unref();
@@ -860,7 +860,7 @@ as in this example:
 'use strict';
 const spawn = require('child_process').spawn;
 
-let child = spawn('sh', ['-c',
+const child = spawn('sh', ['-c',
   `node -e "setInterval(() => {
       console.log(process.pid, 'is alive')
     }, 500);"`
@@ -1107,21 +1107,21 @@ const fs = require('fs');
 const child_process = require('child_process');
 
 const child = child_process.spawn('ls', {
-    stdio: [
-      0, // Use parents stdin for child
-      'pipe', // Pipe child's stdout to parent
-      fs.openSync('err.out', 'w') // Direct child's stderr to a file
-    ]
+  stdio: [
+    0, // Use parent's stdin for child
+    'pipe', // Pipe child's stdout to parent
+    fs.openSync('err.out', 'w') // Direct child's stderr to a file
+  ]
 });
 
-assert.equal(child.stdio[0], null);
-assert.equal(child.stdio[0], child.stdin);
+assert.strictEqual(child.stdio[0], null);
+assert.strictEqual(child.stdio[0], child.stdin);
 
 assert(child.stdout);
-assert.equal(child.stdio[1], child.stdout);
+assert.strictEqual(child.stdio[1], child.stdout);
 
-assert.equal(child.stdio[2], null);
-assert.equal(child.stdio[2], child.stderr);
+assert.strictEqual(child.stdio[2], null);
+assert.strictEqual(child.stdio[2], child.stderr);
 ```
 
 ### child.stdout

doc/api/crypto.md

@@ -1082,26 +1082,15 @@ deprecated: v0.11.13
 
 > Stability: 0 - Deprecated: Use [`tls.createSecureContext()`][] instead.
 
-The `crypto.createCredentials()` method is a deprecated alias for creating
-and returning a `tls.SecureContext` object. The `crypto.createCredentials()`
-method should not be used.
+- `details` {Object} Identical to [`tls.createSecureContext()`][].
 
-The optional `details` argument is a hash object with keys:
+The `crypto.createCredentials()` method is a deprecated function for creating
+and returning a `tls.SecureContext`. It should not be used. Replace it with
+[`tls.createSecureContext()`][] which has the exact same arguments and return
+value.
 
-* `pfx` : {String|Buffer} - PFX or PKCS12 encoded private
-  key, certificate and CA certificates
-* `key` : {String} - PEM encoded private key
-* `passphrase` : {String} - passphrase for the private key or PFX
-* `cert` : {String} - PEM encoded certificate
-* `ca` : {String|Array} - Either a string or array of strings of PEM encoded CA
-  certificates to trust.
-* `crl` : {String|Array} - Either a string or array of strings of PEM encoded CRLs
-  (Certificate Revocation List)
-* `ciphers`: {String} using the [OpenSSL cipher list format][] describing the
-  cipher algorithms to use or exclude.
-
-If no 'ca' details are given, Node.js will use Mozilla's default
-[publicly trusted list of CAs][].
+Returns a `tls.SecureContext`, as-if [`tls.createSecureContext()`][] had been
+called.
 
 ### crypto.createDecipher(algorithm, password)
 <!-- YAML
@@ -1653,8 +1642,8 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
   </tr>
   <tr>
     <td><code>SSL_OP_CIPHER_SERVER_PREFERENCE</code></td>
-    <td>Uses the server's preferences instead of the clients when selecting a
-    cipher. See
+    <td>Attempts to use the server's preferences instead of the client's when
+    selecting a cipher. Behaviour depends on protocol version. See
     https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html.</td>
   </tr>
   <tr>
@@ -1682,7 +1671,7 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
   </tr>
   <tr>
     <td><code>SSL_OP_LEGACY_SERVER_CONNECT</code></td>
-    <td>Allow initial connection to servers that do not support RI.</td>
+    <td>Allows initial connection to servers that do not support RI.</td>
   </tr>
   <tr>
     <td><code>SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER</code></td>
@@ -1980,4 +1969,4 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
 [RFC 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt
 [stream]: stream.html
 [stream-writable-write]: stream.html#stream_writable_write_chunk_encoding_callback
-[Crypto Constants]: #crypto_crypto_constants
+[Crypto Constants]: #crypto_crypto_constants_1

doc/api/path.md

@@ -24,7 +24,7 @@ On POSIX:
 
 ```js
 path.basename('C:\\temp\\myfile.html');
-// Returns: 'C:\temp\myfile.html'
+// Returns: 'C:\\temp\\myfile.html'
 ```
 
 On Windows:
@@ -182,37 +182,32 @@ added: v0.11.15
 The `path.format()` method returns a path string from an object. This is the
 opposite of [`path.parse()`][].
 
-The following process is used when constructing the path string:
+When providing properties to the `pathObject` remember that there are
+combinations where one property has priority over another:
 
-* `output` is set to an empty string.
-* If `pathObject.dir` is specified, `pathObject.dir` is appended to `output`
-  followed by the value of `path.sep`;
-* Otherwise, if `pathObject.root` is specified, `pathObject.root` is appended
-  to `output`.
-* If `pathObject.base` is specified, `pathObject.base` is appended to `output`;
-* Otherwise:
-  * If `pathObject.name` is specified, `pathObject.name` is appended to `output`
-  * If `pathObject.ext` is specified, `pathObject.ext` is appended to `output`.
-* Return `output`
+* `pathObject.root` is ignored if `pathObject.dir` is provided
+* `pathObject.ext` and `pathObject.name` are ignored if `pathObject.base` exists
 
 For example, on POSIX:
 
 ```js
-// If `dir` and `base` are provided,
+// If `dir`, `root` and `base` are provided,
 // `${dir}${path.sep}${base}`
-// will be returned.
+// will be returned. `root` is ignored.
 path.format({
+  root: '/ignored',
   dir: '/home/user/dir',
   base: 'file.txt'
 });
 // Returns: '/home/user/dir/file.txt'
 
 // `root` will be used if `dir` is not specified.
 // If only `root` is provided or `dir` is equal to `root` then the
-// platform separator will not be included.
+// platform separator will not be included. `ext` will be ignored.
 path.format({
   root: '/',
-  base: 'file.txt'
+  base: 'file.txt',
+  ext: 'ignored'
 });
 // Returns: '/file.txt'
 
@@ -223,23 +218,14 @@ path.format({
   ext: '.txt'
 });
 // Returns: '/file.txt'
-
-// `base` will be returned if `dir` or `root` are not provided.
-path.format({
-  base: 'file.txt'
-});
-// Returns: 'file.txt'
 ```
 
 On Windows:
 
 ```js
 path.format({
-    root : "C:\\",
-    dir : "C:\\path\\dir",
-    base : "file.txt",
-    ext : ".txt",
-    name : "file"
+  dir : "C:\\path\\dir",
+  base : "file.txt"
 });
 // Returns: 'C:\\path\\dir\\file.txt'
 ```