docs: automate docs with eslint-doc-generator (#61)

.eslintrc.js

@@ -17,6 +17,9 @@ module.exports = {
     env: {
         mocha: true,
     },
+    rules: {
+        "eslint-plugin/require-meta-docs-description": "error",
+    },
     overrides: [
         {
             // these messageIds were used outside

docs/rules/callback-return.md

@@ -1,5 +1,6 @@
-# n/callback-return
-> require `return` statements after callbacks
+# Require `return` statements after callbacks (`n/callback-return`)
+
+<!-- end auto-generated rule header -->
 
 The callback pattern is at the heart of most I/O and event-driven programming
  in JavaScript.

docs/rules/exports-style.md

@@ -1,6 +1,8 @@
-# n/exports-style
-> enforce either `module.exports` or `exports`
-> - ✒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems) can automatically fix some of the problems reported by this rule.
+# Enforce either `module.exports` or `exports` (`n/exports-style`)
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
 
 `module.exports` and `exports` are the same instance by default.
 But those come to be different if one of them is modified.

docs/rules/file-extension-in-import.md

@@ -1,6 +1,8 @@
-# n/file-extension-in-import
-> enforce the style of file extensions in `import` declarations
-> - ✒️ The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems) can automatically fix some of the problems reported by this rule.
+# Enforce the style of file extensions in `import` declarations (`n/file-extension-in-import`)
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
 
 We can omit file extensions in `import`/`export` declarations.
 

docs/rules/global-require.md

@@ -1,5 +1,6 @@
-# n/global-require
-> require `require()` calls to be placed at top-level module scope
+# Require `require()` calls to be placed at top-level module scope (`n/global-require`)
+
+<!-- end auto-generated rule header -->
 
 In Node.js, module dependencies are included using the `require()` function, such as:
 

docs/rules/handle-callback-err.md

@@ -1,5 +1,6 @@
-# n/handle-callback-err
-> require error handling in callbacks
+# Require error handling in callbacks (`n/handle-callback-err`)
+
+<!-- end auto-generated rule header -->
 
 In Node.js, a common pattern for dealing with asynchronous behavior is called the callback pattern.
 This pattern expects an `Error` object or `null` as the first argument of the callback.

docs/rules/no-callback-literal.md

@@ -1,5 +1,6 @@
-# n/no-callback-literal
-> ensure Node.js-style error-first callback pattern is followed
+# Enforce Node.js-style error-first callback pattern is followed (`n/no-callback-literal`)
+
+<!-- end auto-generated rule header -->
 
 When invoking a callback function which uses the Node.js error-first callback pattern, all of your errors should either use the `Error` class or a subclass of it. It is also acceptable to use `undefined` or `null` if there is no error.
 
@@ -28,16 +29,6 @@ callback(new Error('some error'));
 callback(someVariable);
 ```
 
-### Options
-
-```json
-{
-    "rules": {
-        "n/no-callback-literal": "error"
-    }
-}
-```
-
 ## 🔎 Implementation
 
 - [Rule source](../../lib/rules/no-callback-literal.js)

docs/rules/no-exports-assign.md

@@ -1,6 +1,8 @@
-# n/no-exports-assign
-> disallow the assignment to `exports`
-> - ⭐️ This rule is included in `plugin:n/recommended` preset.
+# Disallow the assignment to `exports` (`n/no-exports-assign`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
+
+<!-- end auto-generated rule header -->
 
 To assign to `exports` variable would not work as expected.
 

docs/rules/no-extraneous-import.md

@@ -1,6 +1,8 @@
-# n/no-extraneous-import
-> disallow `import` declarations which import extraneous modules
-> - ⭐️ This rule is included in `plugin:n/recommended` preset.
+# Disallow `import` declarations which import extraneous modules (`n/no-extraneous-import`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
+
+<!-- end auto-generated rule header -->
 
 If an `import` declaration's source is extraneous (it's not written in `package.json`), the program works in local, but will not work after dependencies are re-installed. It will cause troubles to your team/contributors.
 This rule disallows `import` declarations of extraneous modules.
@@ -47,6 +49,10 @@ If a path is relative, it will be resolved from CWD.
 
 Default is `[]`
 
+#### convertPath
+
+TODO
+
 ### Shared Settings
 
 The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings).

docs/rules/no-extraneous-require.md

@@ -1,6 +1,8 @@
-# n/no-extraneous-require
-> disallow `require()` expressions which import extraneous modules
-> - ⭐️ This rule is included in `plugin:n/recommended` preset.
+# Disallow `require()` expressions which import extraneous modules (`n/no-extraneous-require`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
+
+<!-- end auto-generated rule header -->
 
 If a `require()`'s target is extraneous (it's not written in `package.json`), the program works in local, but will not work after dependencies are re-installed. It will cause troubles to your team/contributors.
 This rule disallows `require()` of extraneous modules.
@@ -55,6 +57,10 @@ When an import path does not exist, this rule checks whether or not any of `path
 
 Default is `[".js", ".json", ".node"]`.
 
+#### convertPath
+
+TODO
+
 ### Shared Settings
 
 The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings).

docs/rules/no-hide-core-modules.md

@@ -1,6 +1,8 @@
-# n/no-hide-core-modules
-> disallow third-party modules which are hiding core modules
-> - ⛔ This rule has been deprecated.
+# Disallow third-party modules which are hiding core modules (`n/no-hide-core-modules`)
+
+❌ This rule is deprecated.
+
+<!-- end auto-generated rule header -->
 
 **:warning: This is deprecated since v4.2.0.** This rule was based on an invalid assumption. See also [#69](https://github.com/mysticatea/eslint-plugin-node/issues/69).
 

docs/rules/no-missing-import.md

@@ -1,6 +1,8 @@
-# n/no-missing-import
-> disallow `import` declarations which import non-existence modules
-> - ⭐️ This rule is included in `plugin:n/recommended` preset.
+# Disallow `import` declarations which import non-existence modules (`n/no-missing-import`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
+
+<!-- end auto-generated rule header -->
 
 This is similar to [no-missing-require](no-missing-require.md), but this rule handles `import` and `export` declarations.
 

docs/rules/no-missing-require.md

@@ -1,6 +1,8 @@
-# n/no-missing-require
-> disallow `require()` expressions which import non-existence modules
-> - ⭐️ This rule is included in `plugin:n/recommended` preset.
+# Disallow `require()` expressions which import non-existence modules (`n/no-missing-require`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
+
+<!-- end auto-generated rule header -->
 
 Maybe we cannot find typo of import paths until run it, so this rule checks import paths.
 

docs/rules/no-mixed-requires.md

@@ -1,5 +1,6 @@
-# n/no-mixed-requires
-> disallow `require` calls to be mixed with regular variable declarations
+# Disallow `require` calls to be mixed with regular variable declarations (`n/no-mixed-requires`)
+
+<!-- end auto-generated rule header -->
 
 In the Node.js community it is often customary to separate initializations with calls to `require` modules from other variable declarations, sometimes also grouping them by the type of module. This rule helps you enforce this convention.
 

docs/rules/no-new-require.md

@@ -1,5 +1,6 @@
-# n/no-new-require
-> disallow `new` operators with calls to `require`
+# Disallow `new` operators with calls to `require` (`n/no-new-require`)
+
+<!-- end auto-generated rule header -->
 
 The `require` function is used to include modules that exist in separate files, such as:
 

docs/rules/no-path-concat.md

@@ -1,5 +1,6 @@
-# n/no-path-concat
-> disallow string concatenation with `__dirname` and `__filename`
+# Disallow string concatenation with `__dirname` and `__filename` (`n/no-path-concat`)
+
+<!-- end auto-generated rule header -->
 
 In Node.js, the `__dirname` and `__filename` global variables contain the directory path and the file path of the currently executing script file, respectively. Sometimes, developers try to use these variables to create paths to other files, such as:
 

docs/rules/no-process-env.md

@@ -1,5 +1,6 @@
-# n/no-process-env
-> disallow the use of `process.env`
+# Disallow the use of `process.env` (`n/no-process-env`)
+
+<!-- end auto-generated rule header -->
 
 The `process.env` object in Node.js is used to store deployment/configuration parameters. Littering it through out a project could lead to maintenance issues as it's another kind of global dependency. As such, it could lead to merge conflicts in a multi-user setup and deployment issues in a multi-server setup. Instead, one of the best practices is to define all those parameters in a single configuration/settings file which could be accessed throughout the project.
 

docs/rules/no-process-exit.md

@@ -1,5 +1,8 @@
-# n/no-process-exit
-> disallow the use of `process.exit()`
+# Disallow the use of `process.exit()` (`n/no-process-exit`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
+
+<!-- end auto-generated rule header -->
 
 The `process.exit()` method in Node.js is used to immediately stop the Node.js process and exit. This is a dangerous operation because it can occur in any method at any point in time, potentially stopping a Node.js application completely when an error occurs. For example:
 

docs/rules/no-restricted-import.md

@@ -1,5 +1,6 @@
-# n/no-restricted-import
-> disallow specified modules when loaded by `import` declarations
+# Disallow specified modules when loaded by `import` declarations (`n/no-restricted-import`)
+
+<!-- end auto-generated rule header -->
 
 ## 📖 Rule Details
 

docs/rules/no-restricted-require.md

@@ -1,5 +1,6 @@
-# n/no-restricted-require
-> disallow specified modules when loaded by `require`
+# Disallow specified modules when loaded by `require` (`n/no-restricted-require`)
+
+<!-- end auto-generated rule header -->
 
 A module in Node.js is a simple or complex functionality organized in a JavaScript file which can be reused throughout the Node.js
 application. The keyword `require` is used in Node.js/CommonJS to import modules into an application. This way you can have dynamic loading where the loaded module name isn't predefined /static, or where you conditionally load a module only if it's "truly required".

docs/rules/no-sync.md

@@ -1,5 +1,6 @@
-# n/no-sync
-> disallow synchronous methods
+# Disallow synchronous methods (`n/no-sync`)
+
+<!-- end auto-generated rule header -->
 
 In Node.js, most I/O is done through asynchronous methods. However, there are often synchronous versions of the asynchronous methods. For example, `fs.exists()` and `fs.existsSync()`. In some contexts, using synchronous operations is okay (if, as with ESLint, you are writing a command line utility). However, in other contexts the use of synchronous operations is considered a bad practice that should be avoided. For example, if you are running a high-travel web server on Node.js, you should consider carefully if you want to allow any synchronous operations that could lock up the server.
 

docs/rules/no-unpublished-bin.md

@@ -1,6 +1,8 @@
-# n/no-unpublished-bin
-> disallow `bin` files that npm ignores
-> - ⭐️ This rule is included in `plugin:n/recommended` preset.
+# Disallow `bin` files that npm ignores (`n/no-unpublished-bin`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
+
+<!-- end auto-generated rule header -->
 
 We can publish CLI commands by `npm`. It uses `bin` field of `package.json`.
 
@@ -85,7 +87,6 @@ For example:
 In this style, this option has the following shape as the same expression as above: `{include: [<targetFiles>], replace: [<fromRegExp>, <toString>]}`.
 In addition, we can specify glob patterns to exclude files.
 
-
 ### Shared Settings
 
 The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings).

docs/rules/no-unpublished-import.md

@@ -1,6 +1,8 @@
-# n/no-unpublished-import
-> disallow `import` declarations which import private modules
-> - ⭐️ This rule is included in `plugin:n/recommended` preset.
+# Disallow `import` declarations which import private modules (`n/no-unpublished-import`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
+
+<!-- end auto-generated rule header -->
 
 This is similar to [no-unpublished-require](no-unpublished-require.md), but this rule handles `import` declarations.
 
@@ -102,6 +104,10 @@ For example:
 In this style, this option has the following shape as the same expression as above: `{include: [<targetFiles>], replace: [<fromRegExp>, <toString>]}`.
 In addition, we can specify glob patterns to exclude files.
 
+#### resolvePaths
+
+TODO
+
 ### Shared Settings
 
 The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings).

docs/rules/no-unpublished-require.md

@@ -1,6 +1,8 @@
-# n/no-unpublished-require
-> disallow `require()` expressions which import private modules
-> - ⭐️ This rule is included in `plugin:n/recommended` preset.
+# Disallow `require()` expressions which import private modules (`n/no-unpublished-require`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
+
+<!-- end auto-generated rule header -->
 
 If a `require()` expression's target is not published, the program works in local, but will not work after published to npm.
 This rule disallows `require()` expressions of unpublished files/modules.
@@ -110,6 +112,10 @@ When an import path does not exist, this rule checks whether or not any of `path
 
 Default is `[".js", ".json", ".node"]`.
 
+#### resolvePaths
+
+TODO
+
 ### Shared Settings
 
 The following options can be set by [shared settings](http://eslint.org/docs/user-guide/configuring.html#adding-shared-settings).

docs/rules/no-unsupported-features.md

@@ -1,8 +1,8 @@
-# n/no-unsupported-features
-> disallow unsupported ECMAScript features on the specified version
-> - ⛔ This rule has been deprecated. Use [n/no-unsupported-features/es-syntax](./no-unsupported-features/es-syntax.md) and [n/no-unsupported-features/es-builtins](./no-unsupported-features/es-builtins.md) instead.
+# Disallow unsupported ECMAScript features on the specified version (`n/no-unsupported-features`)
 
-**:warning: This is deprecated since v7.0.0.** Use [n/no-unsupported-features/es-syntax](./no-unsupported-features/es-syntax.md) and [n/no-unsupported-features/es-builtins](./no-unsupported-features/es-builtins.md) instead.
+❌ This rule is deprecated. It was replaced by [`n/no-unsupported-features/es-syntax`](n/no-unsupported-features/es-syntax.md), [`n/no-unsupported-features/es-builtins`](n/no-unsupported-features/es-builtins.md).
+
+<!-- end auto-generated rule header -->
 
 Node.js doesn't support all ECMAScript standard features.
 This rule reports when you used unsupported ECMAScript 2015-2018 features on the specified Node.js version.
@@ -298,7 +298,7 @@ E.g., a use of instance methods.
 
 ## 📚 Further Reading
 
-- http://node.green/
+- <http://node.green/>
 
 [engines]: https://docs.npmjs.com/files/package.json#engines
 

docs/rules/no-unsupported-features/es-builtins.md

@@ -1,6 +1,8 @@
-# n/no-unsupported-features/es-builtins
-> disallow unsupported ECMAScript built-ins on the specified version
-> - ⭐️ This rule is included in `plugin:n/recommended` preset.
+# Disallow unsupported ECMAScript built-ins on the specified version (`n/no-unsupported-features/es-builtins`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
+
+<!-- end auto-generated rule header -->
 
 ECMAScript standard is updating every two months.
 You can check [node.green](https://node.green/) to know which Node.js version supports each ECMAScript feature.

docs/rules/no-unsupported-features/es-syntax.md

@@ -1,6 +1,8 @@
-# n/no-unsupported-features/es-syntax
-> disallow unsupported ECMAScript syntax on the specified version
-> - ⭐️ This rule is included in `plugin:n/recommended` preset.
+# Disallow unsupported ECMAScript syntax on the specified version (`n/no-unsupported-features/es-syntax`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
+
+<!-- end auto-generated rule header -->
 
 ECMAScript standard is updating every two months.
 You can check [node.green](https://node.green/) to know which Node.js version supports each ECMAScript feature.

docs/rules/no-unsupported-features/node-builtins.md

@@ -1,6 +1,8 @@
-# n/no-unsupported-features/node-builtins
-> disallow unsupported Node.js built-in APIs on the specified version
-> - ⭐️ This rule is included in `plugin:n/recommended` preset.
+# Disallow unsupported Node.js built-in APIs on the specified version (`n/no-unsupported-features/node-builtins`)
+
+💼 This rule is enabled in the following configs: ✅ `recommended`, ☑️ `recommended-module`, ✔️ `recommended-script`.
+
+<!-- end auto-generated rule header -->
 
 Node.js community is improving built-in APIs continuously.
 You can check [Node.js Documentation](https://nodejs.org/api/) to know which Node.js version supports each Node.js API.

docs/rules/prefer-global/buffer.md

@@ -1,5 +1,6 @@
-# n/prefer-global/buffer
-> enforce either `Buffer` or `require("buffer").Buffer`
+# Enforce either `Buffer` or `require("buffer").Buffer` (`n/prefer-global/buffer`)
+
+<!-- end auto-generated rule header -->
 
 The `Buffer` class of `buffer` module is defined as a global variable.
 

docs/rules/prefer-global/console.md

@@ -1,5 +1,6 @@
-# n/prefer-global/console
-> enforce either `console` or `require("console")`
+# Enforce either `console` or `require("console")` (`n/prefer-global/console`)
+
+<!-- end auto-generated rule header -->
 
 The `console` module is defined as a global variable.