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

Author: bmish

.eslintrc.json

@@ -19,6 +19,7 @@
     "prefer-arrow-callback": "error",
     "prefer-const": "error",
     "strict": ["error", "global"],
+    "eslint-plugin/require-meta-docs-description": ["error", { "pattern": "^(Enforce|Require|Disallow|Prefer).+\\.$" }],
     "eslint-plugin/prefer-placeholders": "error",
     "eslint-plugin/test-case-shorthand-strings": "error",
     "node/no-unsupported-features": ["error", { "version": 6 }],

README.md

@@ -21,14 +21,14 @@ Enforce best practices for JavaScript promises.
 
 You'll first need to install [ESLint](http://eslint.org):
 
-```
-$ npm install eslint --save-dev
+```sh
+npm install eslint --save-dev
 ```
 
 Next, install `eslint-plugin-promise`:
 
-```
-$ npm install eslint-plugin-promise --save-dev
+```sh
+npm install eslint-plugin-promise --save-dev
 ```
 
 **Note:** If you installed ESLint globally (using the `-g` flag) then you must
@@ -76,32 +76,30 @@ or start with the recommended rule set:
 
 ## Rules
 
-| rule                                                     | description                                                                      | recommended | fixable  |
-| -------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------- | -------- |
-| [`catch-or-return`][catch-or-return]                     | Enforces the use of `catch()` on un-returned promises.                           | :bangbang:  |          |
-| [`no-return-wrap`][no-return-wrap]                       | Avoid wrapping values in `Promise.resolve` or `Promise.reject` when not needed.  | :bangbang:  |          |
-| [`param-names`][param-names]                             | Enforce consistent param names and ordering when creating new promises.          | :bangbang:  |          |
-| [`always-return`][always-return]                         | Return inside each `then()` to create readable and reusable Promise chains.      | :bangbang:  |          |
-| [`no-native`][no-native]                                 | In an ES5 environment, make sure to create a `Promise` constructor before using. |             |          |
-| [`no-nesting`][no-nesting]                               | Avoid nested `then()` or `catch()` statements                                    | :warning:   |          |
-| [`no-promise-in-callback`][no-promise-in-callback]       | Avoid using promises inside of callbacks                                         | :warning:   |          |
-| [`no-callback-in-promise`][no-callback-in-promise]       | Avoid calling `cb()` inside of a `then()` (use [nodeify][] instead)              | :warning:   |          |
-| [`avoid-new`][avoid-new]                                 | Avoid creating `new` promises outside of utility libs (use [pify][] instead)     |             |          |
-| [`no-new-statics`][no-new-statics]                       | Avoid calling `new` on a Promise static method                                   | :bangbang:  | :wrench: |
-| [`no-return-in-finally`][no-return-in-finally]           | Disallow return statements in `finally()`                                        | :warning:   |          |
-| [`valid-params`][valid-params]                           | Ensures the proper number of arguments are passed to Promise functions           | :warning:   |          |
-| [`prefer-await-to-then`][prefer-await-to-then]           | Prefer `await` to `then()`/`catch()`/`finally()` for reading Promise values      | :seven:     |          |
-| [`prefer-await-to-callbacks`][prefer-await-to-callbacks] | Prefer async/await to the callback pattern                                       | :seven:     |          |
-| [`no-multiple-resolved`][no-multiple-resolved]           | Disallow creating new promises with paths that resolve multiple times            |             |          |
-
-**Key**
-
-| icon       | description                                     |
-| ---------- | ----------------------------------------------- |
-| :bangbang: | Reports as error in recommended configuration   |
-| :warning:  | Reports as warning in recommended configuration |
-| :seven:    | ES2017 Async Await rules                        |
-| :wrench:   | Rule is fixable with `eslint --fix`             |
+<!-- begin auto-generated rules list -->
+
+✅ Enabled in the `recommended` configuration.\
+🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).
+
+| Name                                                                 | Description                                                                            | ✅  | 🔧 |
+| :------------------------------------------------------------------- | :------------------------------------------------------------------------------------- | :- | :- |
+| [always-return](docs/rules/always-return.md)                         | Require returning inside each `then()` to create readable and reusable Promise chains. | ✅  |    |
+| [avoid-new](docs/rules/avoid-new.md)                                 | Disallow creating `new` promises outside of utility libs (use [pify][] instead).       |    |    |
+| [catch-or-return](docs/rules/catch-or-return.md)                     | Enforce the use of `catch()` on un-returned promises.                                  | ✅  |    |
+| [no-callback-in-promise](docs/rules/no-callback-in-promise.md)       | Disallow calling `cb()` inside of a `then()` (use [nodeify][] instead).                |    |    |
+| [no-multiple-resolved](docs/rules/no-multiple-resolved.md)           | Disallow creating new promises with paths that resolve multiple times.                 |    |    |
+| [no-native](docs/rules/no-native.md)                                 | Require creating a `Promise` constructor before using it in an ES5 environment.        |    |    |
+| [no-nesting](docs/rules/no-nesting.md)                               | Disallow nested `then()` or `catch()` statements.                                      |    |    |
+| [no-new-statics](docs/rules/no-new-statics.md)                       | Disallow calling `new` on a Promise static method.                                     | ✅  | 🔧 |
+| [no-promise-in-callback](docs/rules/no-promise-in-callback.md)       | Disallow using promises inside of callbacks.                                           |    |    |
+| [no-return-in-finally](docs/rules/no-return-in-finally.md)           | Disallow return statements in `finally()`.                                             |    |    |
+| [no-return-wrap](docs/rules/no-return-wrap.md)                       | Disallow wrapping values in `Promise.resolve` or `Promise.reject` when not needed.     | ✅  |    |
+| [param-names](docs/rules/param-names.md)                             | Enforce consistent param names and ordering when creating new promises.                | ✅  |    |
+| [prefer-await-to-callbacks](docs/rules/prefer-await-to-callbacks.md) | Prefer async/await to the callback pattern.                                            |    |    |
+| [prefer-await-to-then](docs/rules/prefer-await-to-then.md)           | Prefer `await` to `then()`/`catch()`/`finally()` for reading Promise values.           |    |    |
+| [valid-params](docs/rules/valid-params.md)                           | Enforces the proper number of arguments are passed to Promise functions.               |    |    |
+
+<!-- end auto-generated rules list -->
 
 ## Maintainers
 
@@ -114,21 +112,6 @@ or start with the recommended rule set:
 - (c) MMXV jden <mailto:[email protected]> - ISC license.
 - (c) 2016 Jamund Ferguson <mailto:[email protected]> - ISC license.
 
-[catch-or-return]: docs/rules/catch-or-return.md
-[no-return-wrap]: docs/rules/no-return-wrap.md
-[param-names]: docs/rules/param-names.md
-[always-return]: docs/rules/always-return.md
-[no-native]: docs/rules/no-native.md
-[no-nesting]: docs/rules/no-nesting.md
-[no-promise-in-callback]: docs/rules/no-promise-in-callback.md
-[no-callback-in-promise]: docs/rules/no-callback-in-promise.md
-[avoid-new]: docs/rules/avoid-new.md
-[no-new-statics]: docs/rules/no-new-statics.md
-[no-return-in-finally]: docs/rules/no-return-in-finally.md
-[valid-params]: docs/rules/valid-params.md
-[prefer-await-to-then]: docs/rules/prefer-await-to-then.md
-[prefer-await-to-callbacks]: docs/rules/prefer-await-to-callbacks.md
-[no-multiple-resolved]: docs/rules/no-multiple-resolved.md
 [nodeify]: https://www.npmjs.com/package/nodeify
 [pify]: https://www.npmjs.com/package/pify
 [@aaditmshah]: https://github.com/aaditmshah

docs/rules/always-return.md

@@ -1,4 +1,8 @@
-# Return inside each `then()` to create readable and reusable Promise chains (always-return)
+# Require returning inside each `then()` to create readable and reusable Promise chains (`promise/always-return`)
+
+✅ This rule is enabled in the `recommended` config.
+
+<!-- end auto-generated rule header -->
 
 Ensure that inside a `then()` you make sure to `return` a new promise or value.
 See http://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html (rule #5)

docs/rules/avoid-new.md

@@ -1,3 +1,7 @@
-# Avoid creating `new` promises outside of utility libs (use [pify][] instead) (avoid-new)
+# Disallow creating `new` promises outside of utility libs (use [pify][] instead) (`promise/avoid-new`)
+
+✅ This rule is _disabled_ in the `recommended` config.
+
+<!-- end auto-generated rule header -->
 
 [pify]: https://www.npmjs.com/package/pify

docs/rules/catch-or-return.md

@@ -1,4 +1,8 @@
-# Enforces the use of `catch()` on un-returned promises (catch-or-return)
+# Enforce the use of `catch()` on un-returned promises (`promise/catch-or-return`)
+
+✅ This rule is enabled in the `recommended` config.
+
+<!-- end auto-generated rule header -->
 
 Ensure that each time a `then()` is applied to a promise, a `catch()` is applied
 as well. Exceptions are made if you are returning that promise.

docs/rules/no-callback-in-promise.md

@@ -1,4 +1,8 @@
-# Avoid calling `cb()` inside of a `then()` or `catch()` (no-callback-in-promise)
+# Disallow calling `cb()` inside of a `then()` (use [nodeify][] instead) (`promise/no-callback-in-promise`)
+
+✅ This rule will _warn_ in the `recommended` config.
+
+<!-- end auto-generated rule header -->
 
 As a general rule, callbacks should never be directly invoked inside a
 [Promise.prototype.then()] or [Promise.prototype.catch()] method. That's because
@@ -68,3 +72,11 @@ callback code instead of combining the approaches.
   https://nodejs.org/docs/latest-v14.x/api/process.html#process_process_nexttick_callback_args
 [settimeout()]:
   https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout
+
+## Options
+
+### `exceptions`
+
+String list of callback function names to exempt.
+
+[nodeify]: https://www.npmjs.com/package/nodeify

docs/rules/no-multiple-resolved.md

@@ -1,4 +1,6 @@
-# Disallow creating new promises with paths that resolve multiple times (no-multiple-resolved)
+# Disallow creating new promises with paths that resolve multiple times (`promise/no-multiple-resolved`)
+
+<!-- end auto-generated rule header -->
 
 This rule warns of paths that resolve multiple times in executor functions that
 Promise constructors.

docs/rules/no-native.md

@@ -1,4 +1,8 @@
-# In an ES5 environment, make sure to create a `Promise` constructor before using (no-native)
+# Require creating a `Promise` constructor before using it in an ES5 environment (`promise/no-native`)
+
+✅ This rule is _disabled_ in the `recommended` config.
+
+<!-- end auto-generated rule header -->
 
 Ensure that `Promise` is included fresh in each file instead of relying on the
 existence of a native promise implementation. Helpful if you want to use

docs/rules/no-nesting.md

@@ -1,4 +1,8 @@
-# Avoid nested `then()` or `catch()` statements (no-nesting)
+# Disallow nested `then()` or `catch()` statements (`promise/no-nesting`)
+
+✅ This rule will _warn_ in the `recommended` config.
+
+<!-- end auto-generated rule header -->
 
 #### Valid
 

docs/rules/no-new-statics.md

@@ -1,11 +1,14 @@
-# Avoid calling `new` on a Promise static method (no-new-statics)
+# Disallow calling `new` on a Promise static method (`promise/no-new-statics`)
+
+✅ This rule is enabled in the `recommended` config.
+
+🔧 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 -->
 
 Calling a Promise static method with `new` is invalid, resulting in a
 `TypeError` at runtime.
 
-:wrench: The `--fix` option on the command line can automatically fix the
-problems reported by this rule.
-
 ## Rule Details
 
 This rule is aimed at flagging instances where a Promise static method is called