Add rule require-throws

.README/rules/require-returns.md

@@ -1,53 +1,54 @@
 ### `require-returns`
 
-Requires returns are documented.
+Requires that returns are documented.
 
 Will also report if multiple `@returns` tags are present.
 
 #### Options
 
 - `checkConstructors` - A value indicating whether `constructor`s should
-  be checked for `@returns` tags. Defaults to `false`.
+    be checked for `@returns` tags. Defaults to `false`.
 - `checkGetters` - Boolean to determine whether getter methods should
-  be checked for `@returns` tags. Defaults to `true`.
-- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
-    block avoids the need for a `@returns`. Defaults to an array with
-    `inheritdoc`. If you set this array, it will overwrite the default,
+    be checked for `@returns` tags. Defaults to `true`.
+- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the
+    document block avoids the need for a `@returns`. Defaults to an array
+    with `inheritdoc`. If you set this array, it will overwrite the default,
     so be sure to add back `inheritdoc` if you wish its presence to cause
     exemption of the rule.
 - `forceRequireReturn` - Set to `true` to always insist on
-  `@returns` documentation regardless of implicit or explicit `return`'s
-  in the function. May be desired to flag that a project is aware of an
-  `undefined`/`void` return. Defaults to `false`.
+    `@returns` documentation regardless of implicit or explicit `return`'s
+    in the function. May be desired to flag that a project is aware of an
+    `undefined`/`void` return. Defaults to `false`.
 - `forceReturnsWithAsync` - By default `async` functions that do not explicitly
-  return a value pass this rule as an `async` function will always return a
-  `Promise`, even if the `Promise` resolves to void. You can force all `async`
-  functions to require return statements by setting `forceReturnsWithAsync`
-  to `true` on the options object. This may be useful for flagging that there
-  has been consideration of return type. Defaults to `false`.
+    return a value pass this rule as an `async` function will always return a
+    `Promise`, even if the `Promise` resolves to void. You can force all
+    `async` functions to require return statements by setting
+    `forceReturnsWithAsync` to `true` on the options object. This may be useful
+    for flagging that there has been consideration of return type. Defaults
+    to `false`.
 - `contexts` - Set this to an array of strings representing the AST context
-  where you wish the rule to be applied.
-  Overrides the default contexts (see below). Set to `"any"` if you want
-  the rule to apply to any jsdoc block throughout your files (as is necessary
-  for finding function blocks not attached to a function declaration or
-  expression, i.e., `@callback` or `@function` (or its aliases `@func` or
-  `@method`) (including those associated with an `@interface`). This
-  rule will only apply on non-default contexts when there is such a tag
-  present and the `forceRequireReturn` option is set or if the
-  `forceReturnsWithAsync` option is set with a present `@async` tag
-  (since we are not checking against the actual `return` values in these
-  cases).
+    where you wish the rule to be applied.
+    Overrides the default contexts (see below). Set to `"any"` if you want
+    the rule to apply to any jsdoc block throughout your files (as is necessary
+    for finding function blocks not attached to a function declaration or
+    expression, i.e., `@callback` or `@function` (or its aliases `@func` or
+    `@method`) (including those associated with an `@interface`). This
+    rule will only apply on non-default contexts when there is such a tag
+    present and the `forceRequireReturn` option is set or if the
+    `forceReturnsWithAsync` option is set with a present `@async` tag
+    (since we are not checking against the actual `return` values in these
+    cases).
 
 ```js
 'jsdoc/require-returns': ['error', {forceReturnsWithAsync: true}]
 ```
 
-|          |                                                                                                               |
-| -------- | ------------------------------------------------------------------------------------------------------------- |
+|          |         |
+| -------- | ------- |
 | Context  | `ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled |
-| Tags     | `returns`                                                                                                     |
-| Aliases  | `return`                                                                                                      |
-| Options  | `checkConstructors`, `checkGetters`, `contexts`, `exemptedBy`, `forceRequireReturn`, `forceReturnsWithAsync`  |
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`                               |
+| Tags     | `returns` |
+| Aliases  | `return` |
+| Options  | `checkConstructors`, `checkGetters`, `contexts`, `exemptedBy`, `forceRequireReturn`, `forceReturnsWithAsync` |
+| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
 
 <!-- assertions requireReturns -->

.README/rules/require-throws.md

@@ -0,0 +1,32 @@
+### `require-throws`
+
+Requires that throw statements are documented.
+
+#### Options
+
+- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the
+    document block avoids the need for a `@throws`. Defaults to an array
+    with `inheritdoc`. If you set this array, it will overwrite the default,
+    so be sure to add back `inheritdoc` if you wish its presence to cause
+    exemption of the rule.
+- `contexts` - Set this to an array of strings representing the AST context
+    where you wish the rule to be applied.
+    Overrides the default contexts (see below). Set to `"any"` if you want
+    the rule to apply to any jsdoc block throughout your files (as is necessary
+    for finding function blocks not attached to a function declaration or
+    expression, i.e., `@callback` or `@function` (or its aliases `@func` or
+    `@method`) (including those associated with an `@interface`).
+
+```js
+'jsdoc/require-throws': 'error',
+```
+
+| | |
+| -------- | --- |
+| Context  | `ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled |
+| Tags     | `throws` |
+| Aliases  | `exception` |
+| Options  | `contexts`, `exemptedBy` |
+| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
+
+<!-- assertions requireThrows -->

README.md

@@ -12226,56 +12226,57 @@ function quux () {
 <a name="eslint-plugin-jsdoc-rules-require-returns"></a>
 ### <code>require-returns</code>
 
-Requires returns are documented.
+Requires that returns are documented.
 
 Will also report if multiple `@returns` tags are present.
 
 <a name="eslint-plugin-jsdoc-rules-require-returns-options-26"></a>
 #### Options
 
 - `checkConstructors` - A value indicating whether `constructor`s should
-  be checked for `@returns` tags. Defaults to `false`.
+    be checked for `@returns` tags. Defaults to `false`.
 - `checkGetters` - Boolean to determine whether getter methods should
-  be checked for `@returns` tags. Defaults to `true`.
-- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
-    block avoids the need for a `@returns`. Defaults to an array with
-    `inheritdoc`. If you set this array, it will overwrite the default,
+    be checked for `@returns` tags. Defaults to `true`.
+- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the
+    document block avoids the need for a `@returns`. Defaults to an array
+    with `inheritdoc`. If you set this array, it will overwrite the default,
     so be sure to add back `inheritdoc` if you wish its presence to cause
     exemption of the rule.
 - `forceRequireReturn` - Set to `true` to always insist on
-  `@returns` documentation regardless of implicit or explicit `return`'s
-  in the function. May be desired to flag that a project is aware of an
-  `undefined`/`void` return. Defaults to `false`.
+    `@returns` documentation regardless of implicit or explicit `return`'s
+    in the function. May be desired to flag that a project is aware of an
+    `undefined`/`void` return. Defaults to `false`.
 - `forceReturnsWithAsync` - By default `async` functions that do not explicitly
-  return a value pass this rule as an `async` function will always return a
-  `Promise`, even if the `Promise` resolves to void. You can force all `async`
-  functions to require return statements by setting `forceReturnsWithAsync`
-  to `true` on the options object. This may be useful for flagging that there
-  has been consideration of return type. Defaults to `false`.
+    return a value pass this rule as an `async` function will always return a
+    `Promise`, even if the `Promise` resolves to void. You can force all
+    `async` functions to require return statements by setting
+    `forceReturnsWithAsync` to `true` on the options object. This may be useful
+    for flagging that there has been consideration of return type. Defaults
+    to `false`.
 - `contexts` - Set this to an array of strings representing the AST context
-  where you wish the rule to be applied.
-  Overrides the default contexts (see below). Set to `"any"` if you want
-  the rule to apply to any jsdoc block throughout your files (as is necessary
-  for finding function blocks not attached to a function declaration or
-  expression, i.e., `@callback` or `@function` (or its aliases `@func` or
-  `@method`) (including those associated with an `@interface`). This
-  rule will only apply on non-default contexts when there is such a tag
-  present and the `forceRequireReturn` option is set or if the
-  `forceReturnsWithAsync` option is set with a present `@async` tag
-  (since we are not checking against the actual `return` values in these
-  cases).
+    where you wish the rule to be applied.
+    Overrides the default contexts (see below). Set to `"any"` if you want
+    the rule to apply to any jsdoc block throughout your files (as is necessary
+    for finding function blocks not attached to a function declaration or
+    expression, i.e., `@callback` or `@function` (or its aliases `@func` or
+    `@method`) (including those associated with an `@interface`). This
+    rule will only apply on non-default contexts when there is such a tag
+    present and the `forceRequireReturn` option is set or if the
+    `forceReturnsWithAsync` option is set with a present `@async` tag
+    (since we are not checking against the actual `return` values in these
+    cases).
 
 ```js
 'jsdoc/require-returns': ['error', {forceReturnsWithAsync: true}]
 ```
 
-|          |                                                                                                               |
-| -------- | ------------------------------------------------------------------------------------------------------------- |
+|          |         |
+| -------- | ------- |
 | Context  | `ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled |
-| Tags     | `returns`                                                                                                     |
-| Aliases  | `return`                                                                                                      |
-| Options  | `checkConstructors`, `checkGetters`, `contexts`, `exemptedBy`, `forceRequireReturn`, `forceReturnsWithAsync`  |
-| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`                               |
+| Tags     | `returns` |
+| Aliases  | `return` |
+| Options  | `checkConstructors`, `checkGetters`, `contexts`, `exemptedBy`, `forceRequireReturn`, `forceReturnsWithAsync` |
+| Settings | `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
 
 The following patterns are considered problems:
 

src/index.js

@@ -34,6 +34,7 @@ import requireReturns from './rules/requireReturns';
 import requireReturnsCheck from './rules/requireReturnsCheck';
 import requireReturnsDescription from './rules/requireReturnsDescription';
 import requireReturnsType from './rules/requireReturnsType';
+import requireThrows from './rules/requireThrows';
 import validTypes from './rules/validTypes';
 import requireJsdoc from './rules/requireJsdoc';
 
@@ -119,6 +120,7 @@ export default {
     'require-returns-check': requireReturnsCheck,
     'require-returns-description': requireReturnsDescription,
     'require-returns-type': requireReturnsType,
+    'require-throws': requireThrows,
     'valid-types': validTypes,
   },
 };

src/iterateJsdoc.js

@@ -325,6 +325,10 @@ const getUtils = (
     return jsdocUtils.hasReturnValue(node);
   };
 
+  utils.hasThrowValue = () => {
+    return jsdocUtils.hasThrowValue(node);
+  };
+
   utils.isAsync = () => {
     return node.async;
   };

src/jsdocUtils.js

@@ -556,6 +556,61 @@ const hasReturnValue = (node) => {
   }
 };
 
+/**
+ * Checks if a node has a throws statement.
+ *
+ * @param {object} node
+ * @returns {boolean}
+ */
+const hasThrowValue = (node) => {
+  if (!node) {
+    return false;
+  }
+  switch (node.type) {
+  case 'FunctionExpression':
+  case 'FunctionDeclaration':
+  case 'ArrowFunctionExpression': {
+    return node.expression || hasThrowValue(node.body);
+  }
+  case 'BlockStatement': {
+    return node.body.some((bodyNode) => {
+      return bodyNode.type !== 'FunctionDeclaration' && hasThrowValue(bodyNode);
+    });
+  }
+  case 'WhileStatement':
+  case 'DoWhileStatement':
+  case 'ForStatement':
+  case 'ForInStatement':
+  case 'ForOfStatement':
+  case 'WithStatement': {
+    return hasThrowValue(node.body);
+  }
+  case 'IfStatement': {
+    return hasThrowValue(node.consequent) || hasThrowValue(node.alternate);
+  }
+
+  // We only consider it to throw an error if the catch or finally blocks throw an error.
+  case 'TryStatement': {
+    return hasThrowValue(node.handler && node.handler.body) ||
+        hasThrowValue(node.finalizer);
+  }
+  case 'SwitchStatement': {
+    return node.cases.some(
+      (someCase) => {
+        return someCase.consequent.some(hasThrowValue);
+      },
+    );
+  }
+  case 'ThrowStatement': {
+    return true;
+  }
+
+  default: {
+    return false;
+  }
+  }
+};
+
 /** @param {string} tag */
 /*
 const isInlineTag = (tag) => {
@@ -668,6 +723,7 @@ export default {
   hasDefinedTypeReturnTag,
   hasReturnValue,
   hasTag,
+  hasThrowValue,
   isNamepathDefiningTag,
   isValidTag,
   parseClosureTemplateTag,

src/rules/requireThrows.js

@@ -0,0 +1,86 @@
+import iterateJsdoc from '../iterateJsdoc';
+
+/**
+ * We can skip checking for a throws value, in case the documentation is inherited
+ * or the method is either a constructor or an abstract method.
+ *
+ * @param {*} utils
+ *   a reference to the utils which are used to probe if a tag is present or not.
+ * @returns {boolean}
+ *   true in case deep checking can be skipped; otherwise false.
+ */
+const canSkip = (utils) => {
+  return utils.hasATag([
+    // inheritdoc implies that all documentation is inherited
+    // see https://jsdoc.app/tags-inheritdoc.html
+    //
+    // Abstract methods are by definition incomplete,
+    // so it is not necessary to document that they throw an error.
+    'abstract',
+    'virtual',
+
+    // The designated type can itself document `@throws`
+    'type',
+  ]) ||
+    utils.avoidDocs();
+};
+
+export default iterateJsdoc(({
+  report,
+  utils,
+}) => {
+  // A preflight check. We do not need to run a deep check for abstract
+  //  functions.
+  if (canSkip(utils)) {
+    return;
+  }
+
+  const tagName = utils.getPreferredTagName({tagName: 'throws'});
+  if (!tagName) {
+    return;
+  }
+
+  const tags = utils.getTags(tagName);
+  const iteratingFunction = utils.isIteratingFunction();
+
+  // In case the code returns something, we expect a return value in JSDoc.
+  const [tag] = tags;
+  const missingThrowsTag = typeof tag === 'undefined' || tag === null;
+
+  const shouldReport = () => {
+    if (!missingThrowsTag) {
+      return false;
+    }
+
+    return iteratingFunction && utils.hasThrowValue();
+  };
+
+  if (shouldReport()) {
+    report(`Missing JSDoc @${tagName} declaration.`);
+  }
+}, {
+  contextDefaults: true,
+  meta: {
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          contexts: {
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+          exemptedBy: {
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});