doc: add eslint-plugin-markdown

* install eslint-plugin-markdown
* add doc/.eslintrc.yaml
* add `<!-- eslint-disable rule -->` or `<!-- eslint-disable -->`
  for the rest of problematic code
* .js files in doc folder added to .eslintignore
* update Makefile and vcbuild.bat

PR-URL: https://github.com/nodejs/node/pull/12563
Refs: https://github.com/nodejs/node/pull/12557#issuecomment-296015032
Reviewed-By: Teddy Katz <teddy.katz@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Timothy Gu <timothygu99@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
Reviewed-By: Yuta Hiroto <hello@about-hiroppy.com>

18 files changed, 51 insertions, 28 deletions

diff --git a/doc/.eslintrc.yaml b/doc/.eslintrc.yaml
new file mode 100644
index 0000000000..b81bec6508
--- /dev/null
+++ b/doc/.eslintrc.yaml
@@ -0,0 +1,5 @@
+rules:
+  strict: 0
+  no-restricted-properties: 0
+  no-undef: 0
+  no-unused-vars: 0
diff --git a/doc/api/assert.md b/doc/api/assert.md
index 2ab93c8de0..74fd2a37d0 100644
--- a/doc/api/assert.md
+++ b/doc/api/assert.md
@@ -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');
diff --git a/doc/api/cluster.md b/doc/api/cluster.md
index 069f9f2003..858c98dab6 100644
--- a/doc/api/cluster.md
+++ b/doc/api/cluster.md
@@ -523,14 +523,11 @@ When any of the workers die the cluster module will emit the `'exit'` event.
 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);
-    cluster.fork();
-  }
-);
+cluster.on('exit', (worker, code, signal) => {
+  console.log('worker %d died (%s). restarting...',
+              worker.process.pid, signal || code);
+  cluster.fork();
+});
 ```
 
 See [child_process event: 'exit'][].
diff --git a/doc/api/console.md b/doc/api/console.md
index 900a7aa9c1..1fc034e4f8 100644
--- a/doc/api/console.md
+++ b/doc/api/console.md
@@ -135,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';
 
@@ -142,7 +143,7 @@ the default behavior of `console` in Node.js.
 // new impl for assert without monkey-patching.
 const myConsole = Object.create(console, {
   assert: {
-    value(assertion, message, ...args) {
+    value: function assert(assertion, message, ...args) {
       try {
         console.assert(assertion, message, ...args);
       } catch (err) {
@@ -276,7 +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
 ```
diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 6392491f3a..fc41123eba 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -289,7 +289,7 @@ decipher.on('end', () => {
 });
 
 const encrypted =
-  'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504';
+    'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504';
 decipher.write(encrypted, 'hex');
 decipher.end();
 ```
@@ -314,7 +314,7 @@ const crypto = require('crypto');
 const decipher = crypto.createDecipher('aes192', 'a password');
 
 const encrypted =
-  'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504';
+    'ca981be48e90867604588e75d04feabb63cc007a8f8ad89b10616ed84d815504';
 let decrypted = decipher.update(encrypted, 'hex', 'utf8');
 decrypted += decipher.final('utf8');
 console.log(decrypted);
diff --git a/doc/api/debugger.md b/doc/api/debugger.md
index 3807f278bd..090bf7f2a8 100644
--- a/doc/api/debugger.md
+++ b/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;
diff --git a/doc/api/dns.md b/doc/api/dns.md
index b667d7d6f0..48990b5bc8 100644
--- a/doc/api/dns.md
+++ b/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,
diff --git a/doc/api/fs.md b/doc/api/fs.md
index e41b135b6e..41b01c9c70 100644
--- a/doc/api/fs.md
+++ b/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:
 
-```txt
+```
 Stats {
   dev: 2114,
   ino: 48064969,
diff --git a/doc/api/http.md b/doc/api/http.md
index 3cf80923dd..ba76269c0a 100644
--- a/doc/api/http.md
+++ b/doc/api/http.md
@@ -12,6 +12,7 @@ user is able to stream data.
 
 HTTP message headers are represented by an object like this:
 
+<!-- eslint-disable -->
 ```js
 { 'content-length': '123',
   'content-type': 'text/plain',
@@ -34,6 +35,7 @@ property, which is an array of `[key, value, key2, value2, ...]`.  For
 example, the previous message header object might have a `rawHeaders`
 list like the following:
 
+<!-- eslint-disable semi -->
 ```js
 [ 'ConTent-Length', '123456',
   'content-LENGTH', '123',
@@ -1460,6 +1462,7 @@ Accept: text/plain\r\n
 
 Then `request.url` will be:
 
+<!-- eslint-disable semi -->
 ```js
 '/status?name=ryan'
 ```
diff --git a/doc/api/modules.md b/doc/api/modules.md
index 48a4d1f3cf..5f1cf96ebb 100644
--- a/doc/api/modules.md
+++ b/doc/api/modules.md
@@ -67,11 +67,7 @@ The module system is implemented in the `require('module')` module.
 
 When a file is run directly from Node.js, `require.main` is set to its
 `module`. That means that you can determine whether a file has been run
-directly by testing
-
-```js
-require.main === module;
-```
+directly by testing `require.main === module`.
 
 For a file `foo.js`, this will be `true` if run via `node foo.js`, but
 `false` if run by `require('./foo')`.
@@ -556,6 +552,7 @@ exports = { hello: false };  // Not exported, only available in the module
 When the `module.exports` property is being completely replaced by a new
 object, it is common to also reassign `exports`, for example:
 
+<!-- eslint-disable func-name-matching -->
 ```js
 module.exports = exports = function Constructor() {
   // ... etc.
diff --git a/doc/api/os.md b/doc/api/os.md
index 44bbe0b437..b9f2775ce6 100644
--- a/doc/api/os.md
+++ b/doc/api/os.md
@@ -71,6 +71,7 @@ The properties included on each object include:
 
 For example:
 
+<!-- eslint-disable semi -->
 ```js
 [
   {
@@ -253,6 +254,7 @@ The properties available on the assigned network address object include:
 * `scopeid` {number} The numeric IPv6 scope ID (only specified when `family`
   is `IPv6`)
 
+<!-- eslint-disable -->
 ```js
 {
   lo: [
diff --git a/doc/api/process.md b/doc/api/process.md
index 3f7c6d4e5a..3f853e5511 100644
--- a/doc/api/process.md
+++ b/doc/api/process.md
@@ -528,7 +528,8 @@ running the `./configure` script.
 
 An example of the possible output looks like:
 
-```txt
+<!-- eslint-disable -->
+```js
 {
   target_defaults:
    { cflags: [],
@@ -745,6 +746,7 @@ See environ(7).
 
 An example of this object looks like:
 
+<!-- eslint-disable -->
 ```js
 {
   TERM: 'xterm-256color',
@@ -832,12 +834,14 @@ $ node --harmony script.js --version
 
 Results in `process.execArgv`:
 
+<!-- eslint-disable semi -->
 ```js
 ['--harmony']
 ```
 
 And `process.argv`:
 
+<!-- eslint-disable semi -->
 ```js
 ['/usr/local/bin/node', 'script.js', '--version']
 ```
@@ -854,6 +858,7 @@ that started the Node.js process.
 
 For example:
 
+<!-- eslint-disable semi -->
 ```js
 '/usr/local/bin/node'
 ```
@@ -1173,6 +1178,7 @@ console.log(process.memoryUsage());
 
 Will generate:
 
+<!-- eslint-disable -->
 ```js
 {
   rss: 4935680,
@@ -1344,6 +1350,7 @@ tarball.
 
 For example:
 
+<!-- eslint-disable -->
 ```js
 {
   name: 'node',
@@ -1705,6 +1712,7 @@ console.log(process.versions);
 
 Will generate an object similar to:
 
+<!-- eslint-disable -->
 ```js
 {
   http_parser: '2.3.0',
diff --git a/doc/api/querystring.md b/doc/api/querystring.md
index d82bf645e4..580ae676be 100644
--- a/doc/api/querystring.md
+++ b/doc/api/querystring.md
@@ -59,6 +59,7 @@ collection of key and value pairs.
 
 For example, the query string `'foo=bar&abc=xyz&abc=123'` is parsed into:
 
+<!-- eslint-disable -->
 ```js
 {
   foo: 'bar',
diff --git a/doc/api/readline.md b/doc/api/readline.md
index b4c0df9f43..2a8c2aed88 100644
--- a/doc/api/readline.md
+++ b/doc/api/readline.md
@@ -414,7 +414,7 @@ For instance: `[[substr1, substr2, ...], originalsubstring]`.
 ```js
 function completer(line) {
   const completions = '.help .error .exit .quit .q'.split(' ');
-  const hits = completions.filter((c) => { return c.indexOf(line) === 0; });
+  const hits = completions.filter((c) => c.indexOf(line) === 0);
   // show all completions if none found
   return [hits.length ? hits : completions, line];
 }
diff --git a/doc/api/repl.md b/doc/api/repl.md
index dff2f8f51d..e5d2fa41d6 100644
--- a/doc/api/repl.md
+++ b/doc/api/repl.md
@@ -40,6 +40,7 @@ The following special commands are supported by all REPL instances:
   `> .load ./file/to/load.js`
 * `.editor` - Enter editor mode (`<ctrl>-D` to finish, `<ctrl>-C` to cancel)
 
+<!-- eslint-disable -->
 ```js
 > .editor
 // Entering editor mode (^D to finish, ^C to cancel)
@@ -75,6 +76,7 @@ evaluation function when the `repl.REPLServer` instance is created.
 
 The default evaluator supports direct evaluation of JavaScript expressions:
 
+<!-- eslint-disable -->
 ```js
 > 1 + 1
 2
@@ -103,6 +105,7 @@ repl.start('> ').context.m = msg;
 
 Properties in the `context` object appear as local within the REPL:
 
+<!-- eslint-disable -->
 ```js
 $ node repl_test.js
 > m
@@ -132,6 +135,7 @@ REPL environment when used. For instance, unless otherwise declared as a
 global or scoped variable, the input `fs` will be evaluated on-demand as
 `global.fs = require('fs')`.
 
+<!-- eslint-disable -->
 ```js
 > fs.createReadStream('./some/file');
 ```
@@ -142,6 +146,7 @@ The default evaluator will, by default, assign the result of the most recently
 evaluated expression to the special variable `_` (underscore).
 Explicitly setting `_` to a value will disable this behavior.
 
+<!-- eslint-disable -->
 ```js
 > [ 'a', 'b', 'c' ]
 [ 'a', 'b', 'c' ]
@@ -288,6 +293,7 @@ r.on('reset', initializeContext);
 When this code is executed, the global `'m'` variable can be modified but then
 reset to its initial value using the `.clear` command:
 
+<!-- eslint-disable -->
 ```js
 $ ./node example.js
 > m
@@ -438,6 +444,7 @@ Node.js itself uses the `repl` module to provide its own interactive interface
 for executing JavaScript. This can be used by executing the Node.js binary
 without passing any arguments (or by passing the `-i` argument):
 
+<!-- eslint-disable -->
 ```js
 $ node
 > const a = [1, 2, 3];
diff --git a/doc/api/stream.md b/doc/api/stream.md
index da6c51907a..c8462760f5 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -280,7 +280,7 @@ has been called, and all data has been flushed to the underlying system.
 
 ```js
 const writer = getWritableStreamSomehow();
-for (var i = 0; i < 100; i++) {
+for (let i = 0; i < 100; i++) {
   writer.write(`hello, #${i}!\n`);
 }
 writer.end('This is the end\n');
diff --git a/doc/api/v8.md b/doc/api/v8.md
index 8d5d428e56..e766d7c101 100644
--- a/doc/api/v8.md
+++ b/doc/api/v8.md
@@ -116,6 +116,7 @@ swapped out by the operating system.
 
 For example:
 
+<!-- eslint-disable -->
 ```js
 {
   total_heap_size: 7326976,
diff --git a/doc/api/zlib.md b/doc/api/zlib.md
index 73aa81ede9..340470a4e1 100644
--- a/doc/api/zlib.md
+++ b/doc/api/zlib.md
@@ -151,8 +151,9 @@ From `zlib/zconf.h`, modified to node.js's usage:
 
 The memory requirements for deflate are (in bytes):
 
+<!-- eslint-disable semi -->
 ```js
-(1 << (windowBits + 2)) + (1 << (memLevel + 9));
+(1 << (windowBits + 2)) + (1 << (memLevel + 9))
 ```
 
 That is: 128K for windowBits=15  +  128K for memLevel = 8
@@ -167,12 +168,7 @@ const options = { windowBits: 14, memLevel: 7 };
 
 This will, however, generally degrade compression.
 
-The memory requirements for inflate are (in bytes)
-
-```js
-1 << windowBits;
-```
-
+The memory requirements for inflate are (in bytes) `1 << windowBits`.
 That is, 32K for windowBits=15 (default value) plus a few kilobytes
 for small objects.