doc, tools: use eslint-plugin-markdown

.eslintignore

@@ -7,3 +7,4 @@ test/tmp*/
 tools/eslint
 node_modules
 benchmark/tmp/
+doc/**/*.js

.eslintrc.yaml

@@ -1,5 +1,8 @@
 root: true
 
+plugins:
+  - markdown
+
 env:
   node: true
   es6: true

Makefile

@@ -855,8 +855,8 @@ bench-ci: bench
 
 jslint:
 	@echo "Running JS linter..."
-	$(NODE) tools/eslint/bin/eslint.js --cache --rulesdir=tools/eslint-rules \
-	  benchmark lib test tools
+	$(NODE) tools/eslint/bin/eslint.js --cache --rulesdir=tools/eslint-rules --ext=.js,.md \
+	  benchmark doc lib test tools
 
 jslint-ci:
 	@echo "Running JS linter..."

doc/.eslintrc.yaml

@@ -0,0 +1,12 @@
+## Docs-specific linter rules
+
+rules:
+  # ease some restrictions in doc examples
+  no-restricted-properties: 0
+  no-undef: 0
+  no-unused-vars: 0
+  strict: 0
+
+  # add new ECMAScript features gradually
+  no-var: 2
+  prefer-const: 2

doc/api/assert.md

@@ -63,18 +63,18 @@ are evaluated also:
 const assert = require('assert');
 
 const obj1 = {
-  a : {
-    b : 1
+  a: {
+    b: 1
   }
 };
 const obj2 = {
-  a : {
-    b : 2
+  a: {
+    b: 2
   }
 };
 const obj3 = {
-  a : {
-    b : 1
+  a: {
+    b: 1
   }
 };
 const obj4 = Object.create(obj1);
@@ -322,18 +322,18 @@ Tests for any deep inequality. Opposite of [`assert.deepEqual()`][].
 const assert = require('assert');
 
 const obj1 = {
-  a : {
-    b : 1
+  a: {
+    b: 1
   }
 };
 const obj2 = {
-  a : {
-    b : 2
+  a: {
+    b: 2
   }
 };
 const obj3 = {
-  a : {
-    b : 1
+  a: {
+    b: 1
   }
 };
 const obj4 = Object.create(obj1);
@@ -368,10 +368,10 @@ Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual()`][].
 ```js
 const assert = require('assert');
 
-assert.notDeepEqual({a:1}, {a:'1'});
+assert.notDeepEqual({a: 1}, {a: '1'});
 // AssertionError: { a: 1 } notDeepEqual { a: '1' }
 
-assert.notDeepStrictEqual({a:1}, {a:'1'});
+assert.notDeepStrictEqual({a: 1}, {a: '1'});
 // OK
 ```
 
@@ -542,7 +542,7 @@ assert.throws(
     throw new Error('Wrong value');
   },
   function(err) {
-    if ( (err instanceof Error) && /value/.test(err) ) {
+    if ((err instanceof Error) && /value/.test(err)) {
       return true;
     }
   },
@@ -554,6 +554,7 @@ Note that `error` can not be a string. If a string is provided as the second
 argument, then `error` is assumed to be omitted and the string will be used for
 `message` instead. This can lead to easy-to-miss mistakes:
 
+<!-- eslint-disable assert-throws-arguments -->
 ```js
 // THIS IS A MISTAKE! DO NOT DO THIS!
 assert.throws(myFunction, 'missing foo', 'did not throw with expected message');

doc/api/buffer.md

@@ -959,7 +959,7 @@ Example: Copy an ASCII string into a `Buffer`, one byte at a time
 const str = 'Node.js';
 const buf = Buffer.allocUnsafe(str.length);
 
-for (let i = 0; i < str.length ; i++) {
+for (let i = 0; i < str.length; i++) {
   buf[i] = str.charCodeAt(i);
 }
 
@@ -1087,7 +1087,7 @@ byte 16 through byte 19 into `buf2`, starting at the 8th byte in `buf2`
 const buf1 = Buffer.allocUnsafe(26);
 const buf2 = Buffer.allocUnsafe(26).fill('!');
 
-for (let i = 0 ; i < 26 ; i++) {
+for (let i = 0; i < 26; i++) {
   // 97 is the decimal ASCII value for 'a'
   buf1[i] = i + 97;
 }
@@ -1104,7 +1104,7 @@ overlapping region within the same `Buffer`
 ```js
 const buf = Buffer.allocUnsafe(26);
 
-for (let i = 0 ; i < 26 ; i++) {
+for (let i = 0; i < 26; i++) {
   // 97 is the decimal ASCII value for 'a'
   buf[i] = i + 97;
 }
@@ -1871,7 +1871,7 @@ one byte from the original `Buffer`
 ```js
 const buf1 = Buffer.allocUnsafe(26);
 
-for (let i = 0 ; i < 26 ; i++) {
+for (let i = 0; i < 26; i++) {
   // 97 is the decimal ASCII value for 'a'
   buf1[i] = i + 97;
 }
@@ -2021,9 +2021,9 @@ const json = JSON.stringify(buf);
 console.log(json);
 
 const copy = JSON.parse(json, (key, value) => {
-  return value && value.type === 'Buffer'
-    ? Buffer.from(value.data)
-    : value;
+  return value && value.type === 'Buffer' ?
+    Buffer.from(value.data) :
+    value;
 });
 
 // Prints: <Buffer 01 02 03 04 05>
@@ -2049,7 +2049,7 @@ Examples:
 ```js
 const buf1 = Buffer.allocUnsafe(26);
 
-for (let i = 0 ; i < 26 ; i++) {
+for (let i = 0; i < 26; i++) {
   // 97 is the decimal ASCII value for 'a'
   buf1[i] = i + 97;
 }

doc/api/child_process.md

@@ -101,7 +101,9 @@ bat.stderr.on('data', (data) => {
 bat.on('exit', (code) => {
   console.log(`Child exited with code ${code}`);
 });
+```
 
+```js
 // OR...
 const exec = require('child_process').exec;
 exec('my.bat', (err, stdout, stderr) => {
@@ -195,14 +197,14 @@ The `options` argument may be passed as the second argument to customize how
 the process is spawned. The default options are:
 
 ```js
-{
+const defaults = {
   encoding: 'utf8',
   timeout: 0,
-  maxBuffer: 200*1024,
+  maxBuffer: 200 * 1024,
   killSignal: 'SIGTERM',
   cwd: null,
   env: null
-}
+};
 ```
 
 If `timeout` is greater than `0`, the parent will send the signal
@@ -362,10 +364,10 @@ trigger arbitrary command execution.**
 A third argument may be used to specify additional options, with these defaults:
 
 ```js
-{
+const defaults = {
   cwd: undefined,
   env: process.env
-}
+};
 ```
 
 Use `cwd` to specify the working directory from which the process is spawned.
@@ -931,13 +933,17 @@ as in this example:
 'use strict';
 const spawn = require('child_process').spawn;
 
-const child = spawn('sh', ['-c',
-  `node -e "setInterval(() => {
+const child = spawn(
+  'sh',
+  [
+    '-c',
+    `node -e "setInterval(() => {
       console.log(process.pid, 'is alive')
     }, 500);"`
   ], {
     stdio: ['inherit', 'inherit', 'inherit']
-  });
+  }
+);
 
 setTimeout(() => {
   child.kill(); // does not terminate the node process in the shell

doc/api/cluster.md

@@ -525,7 +525,7 @@ This can be used to restart the worker by calling `.fork()` again.
 ```js
 cluster.on('exit', (worker, code, signal) => {
   console.log('worker %d died (%s). restarting...',
-    worker.process.pid, signal || code);
+              worker.process.pid, signal || code);
   cluster.fork();
 });
 ```

doc/api/console.md

@@ -69,6 +69,9 @@ or `console.Console`:
 
 ```js
 const Console = require('console').Console;
+```
+
+```js
 const Console = console.Console;
 ```
 
@@ -132,6 +135,7 @@ by extending Node.js' `console` and overriding the `console.assert()` method.
 In the following example, a simple module is created that extends and overrides
 the default behavior of `console` in Node.js.
 
+<!-- eslint-disable func-name-matching -->
 ```js
 'use strict';
 
@@ -273,9 +277,7 @@ prints the result to `stdout`:
 
 ```js
 console.time('100-elements');
-for (let i = 0; i < 100; i++) {
-  ;
-}
+for (let i = 0; i < 100; i++) {}
 console.timeEnd('100-elements');
 // prints 100-elements: 225.438ms
 ```

doc/api/crypto.md

@@ -288,7 +288,8 @@ decipher.on('end', () => {
   // Prints: some clear text data
 });
 
-const encrypted = 'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504';
+const encrypted =
+    'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504';
 decipher.write(encrypted, 'hex');
 decipher.end();
 ```
@@ -312,7 +313,8 @@ Example: Using the [`decipher.update()`][] and [`decipher.final()`][] methods:
 const crypto = require('crypto');
 const decipher = crypto.createDecipher('aes192', 'a password');
 
-const encrypted = 'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504';
+const encrypted =
+    'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504';
 let decrypted = decipher.update(encrypted, 'hex', 'utf8');
 decrypted += decipher.final('utf8');
 console.log(decrypted);

doc/api/debugger.md

@@ -26,6 +26,7 @@ inspection are possible.
 Inserting the statement `debugger;` into the source code of a script will
 enable a breakpoint at that position in the code:
 
+<!-- eslint-disable no-debugger -->
 ```js
 // myscript.js
 global.x = 5;

doc/api/dgram.md

@@ -20,7 +20,7 @@ server.on('message', (msg, rinfo) => {
 });
 
 server.on('listening', () => {
-  var address = server.address();
+  const address = server.address();
   console.log(`server listening ${address.address}:${address.port}`);
 });
 
@@ -146,7 +146,7 @@ server.on('message', (msg, rinfo) => {
 });
 
 server.on('listening', () => {
-  var address = server.address();
+  const address = server.address();
   console.log(`server listening ${address.address}:${address.port}`);
 });
 

doc/api/dns.md

@@ -293,6 +293,7 @@ function will contain an array of objects with the following properties:
 
 For example:
 
+<!-- eslint-disable -->
 ```js
 {
   flags: 's',
@@ -352,6 +353,7 @@ be an object with the following properties:
 * `expire`
 * `minttl`
 
+<!-- eslint-disable -->
 ```js
 {
   nsname: 'ns.example.com',
@@ -382,6 +384,7 @@ be an array of objects with the following properties:
 * `port`
 * `name`
 
+<!-- eslint-disable -->
 ```js
 {
   priority: 10,

doc/api/domain.md

@@ -162,7 +162,7 @@ function handleRequest(req, res) {
       setTimeout(() => {
         // Whoops!
         flerb.bark();
-      });
+      }, timeout);
       break;
     default:
       res.end('ok');

doc/api/fs.md

@@ -217,7 +217,7 @@ synchronous counterparts are of this type.
 For a regular file [`util.inspect(stats)`][] would return a string very
 similar to this:
 
-```js
+```
 Stats {
   dev: 2114,
   ino: 48064969,
@@ -630,13 +630,13 @@ default value of 64 kb for the same parameter.
 `options` is an object or string with the following defaults:
 
 ```js
-{
+const defaults = {
   flags: 'r',
   encoding: null,
   fd: null,
   mode: 0o666,
   autoClose: true
-}
+};
 ```
 
 `options` can include `start` and `end` values to read a range of bytes from
@@ -696,13 +696,13 @@ Returns a new [`WriteStream`][] object. (See [Writable Stream][]).
 `options` is an object or string with the following defaults:
 
 ```js
-{
+const defaults = {
   flags: 'w',
   defaultEncoding: 'utf8',
   fd: null,
   mode: 0o666,
   autoClose: true
-}
+};
 ```
 
 `options` may also include a `start` option to allow writing data at