feat: add require-rejects rule; fixes #755

Author: brettz9

.README/README.md

@@ -84,6 +84,11 @@ export default [
               'type',
             ],
           },
+          rejects: {
+            required: [
+              'type',
+            ],
+          },
         },
       */
     }
@@ -262,6 +267,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/require-property-name": 1, // Recommended
         "jsdoc/require-property-type": 1, // Recommended in non-TS configs
         "jsdoc/require-property": 1, // Recommended
+        "jsdoc/require-rejects": 1, // Recommended
         "jsdoc/require-returns-check": 1, // Recommended
         "jsdoc/require-returns-description": 1, // Recommended
         "jsdoc/require-returns-type": 1, // Recommended in non-TS configs

.README/rules/require-rejects.md

@@ -0,0 +1,24 @@
+# `require-rejects`
+
+Requires a (non-standard) `@rejects` tag be added for detectable `Promise`
+rejections.
+
+## Options
+
+{"gitdown": "options"}
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|``|
+|Recommended|false|
+|Settings||
+|Options|`contexts`, `exemptedBy`|
+
+## Failing examples
+
+<!-- assertions-failing requireRejects -->
+
+## Passing examples
+
+<!-- assertions-passing requireRejects -->

.README/rules/require-throws.md

@@ -4,13 +4,15 @@
 
 Requires that throw statements are documented.
 
-Note that since throw statements within async functions end up as rejected
-Promises, they are not considered as throw statements for the purposes of this
-rule. See [issue 755](https://github.com/gajus/eslint-plugin-jsdoc/issues/755)
-for our desire for a separate tag to document rejection types and see
+See
 [this discussion](https://stackoverflow.com/questions/50071115/typescript-promise-rejection-type)
 on why TypeScript doesn't offer such a feature.
 
+Note that since throw statements within async functions end up as rejected
+`Promise`'s, they are not considered as throw statements for the purposes of
+this rule. See the `require-rejects` rule for a non-standard way to document
+`Promise` rejections.
+
 ## Options
 
 {"gitdown": "options"}

README.md

@@ -103,6 +103,11 @@ export default [
               'type',
             ],
           },
+          rejects: {
+            required: [
+              'type',
+            ],
+          },
         },
       */
     }
@@ -289,6 +294,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/require-property-name": 1, // Recommended
         "jsdoc/require-property-type": 1, // Recommended in non-TS configs
         "jsdoc/require-property": 1, // Recommended
+        "jsdoc/require-rejects": 1, // Recommended
         "jsdoc/require-returns-check": 1, // Recommended
         "jsdoc/require-returns-description": 1, // Recommended
         "jsdoc/require-returns-type": 1, // Recommended in non-TS configs
@@ -484,6 +490,7 @@ non-default-recommended fixer).
 |:heavy_check_mark:|| [require-property-description](./docs/rules/require-property-description.md#readme) | Requires that each `@property` tag has a `description` value. |
 |:heavy_check_mark:|| [require-property-name](./docs/rules/require-property-name.md#readme) | Requires that all `@property` tags have names. |
 |:heavy_check_mark: (Off in TS; On in TS flavor)|| [require-property-type](./docs/rules/require-property-type.md#readme) | Requires that each `@property` tag has a type value (in curly brackets). |
+||| [require-rejects](./docs/rules/require-rejects.md#readme) | Requires that Promise rejections are documented with `@rejects` tags. |
 |:heavy_check_mark:|:wrench:| [require-returns](./docs/rules/require-returns.md#readme) | Requires that returns are documented with `@returns`. |
 |:heavy_check_mark:|| [require-returns-check](./docs/rules/require-returns-check.md#readme) | Requires a return statement in function body if a `@returns` tag is specified in JSDoc comment(and reports if multiple `@returns` tags are present). |
 |:heavy_check_mark:|| [require-returns-description](./docs/rules/require-returns-description.md#readme) | Requires that the `@returns` tag has a `description` value (not including `void`/`undefined` type returns). |