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: #12563
Refs: #12557 (comment)
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>

.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,5 @@
+rules:
+  strict: 0
+  no-restricted-properties: 0
+  no-undef: 0
+  no-unused-vars: 0

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');

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'][].

doc/api/console.md

@@ -135,14 +135,15 @@ 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';
 
 // Creates a simple extension of console with a
 // 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
 ```

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);

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/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/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,

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'
 ```

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.

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: [

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',

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',

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];
 }

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];

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');

doc/api/v8.md

@@ -116,6 +116,7 @@ swapped out by the operating system.
 
 For example:
 
+<!-- eslint-disable -->
 ```js
 {
   total_heap_size: 7326976,

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.
 

test/README.md

@@ -352,6 +352,7 @@ A non-op `Function` that can be used for a variety of scenarios.
 
 For instance,
 
+<!-- eslint-disable strict, no-undef -->
 ```js
 const common = require('../common');