Merge branch 'forceReturnsWithAsync'

feat(require-returns): add forceReturnsWithAsync option

Author: brettz9

.README/rules/require-returns.md

@@ -2,11 +2,18 @@
 
 Requires returns are documented.
 
+By default `async` functions that do not explicitly return a value pass this rule. You can force all `async` functions to require return statements by setting `forceReturnsWithAsync` as true on the options object. This may be useful as an `async` function will always return a Promise, even if the Promise returns void.
+
+```js
+'jsdoc/require-jsdoc': ['error', {forceReturnsWithAsync: true}]
+```
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`returns`|
 |Aliases|`return`|
 |Settings|`forceRequireReturn`|
+|Options|`forceReturnsWithAsync`|
 
 <!-- assertions requireReturns -->

README.md

@@ -4567,12 +4567,19 @@ function quux () {
 
 Requires returns are documented.
 
+By default `async` functions that do not explicitly return a value pass this rule. You can force all `async` functions to require return statements by setting `forceReturnsWithAsync` as true on the options object. This may be useful as an `async` function will always return a Promise, even if the Promise returns void.
+
+```js
+'jsdoc/require-jsdoc': ['error', {forceReturnsWithAsync: true}]
+```
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`returns`|
 |Aliases|`return`|
 |Settings|`forceRequireReturn`|
+|Options|`forceReturnsWithAsync`|
 
 The following patterns are considered problems:
 
@@ -4619,19 +4626,30 @@ function quux (foo) {
 /**
  *
  */
-async function quux() {}
+async function quux() {
+}
+// Settings: {"jsdoc":{"forceRequireReturn":true}}
 // Message: Missing JSDoc @returns declaration.
 
 /**
  *
  */
 const quux = async function () {}
+// Settings: {"jsdoc":{"forceRequireReturn":true}}
 // Message: Missing JSDoc @returns declaration.
 
 /**
  *
  */
 const quux = async () => {}
+// Settings: {"jsdoc":{"forceRequireReturn":true}}
+// Message: Missing JSDoc @returns declaration.
+
+/**
+*
+*/
+async function quux () {}
+// Settings: {"jsdoc":{"forceRequireReturn":true}}
 // Message: Missing JSDoc @returns declaration.
 
 /**
@@ -4651,6 +4669,14 @@ const language = {
   }
 }
 // Message: Missing JSDoc @returns declaration.
+
+/**
+ *
+ */
+async function quux () {
+}
+// Options: [{"forceReturnsWithAsync":true}]
+// Message: Missing JSDoc @returns declaration.
 ````
 
 The following patterns are not considered problems:
@@ -4865,6 +4891,35 @@ function quux (req, res , next) {
   return;
 }
 
+/**
+ * @returns {Promise}
+ */
+async function quux () {
+}
+// Settings: {"jsdoc":{"forceRequireReturn":true}}
+
+/**
+ * @returns {Promise}
+ */
+async function quux () {
+}
+// Options: [{"forceReturnsWithAsync":true}]
+
+/**
+ *
+ */
+async function quux () {}
+
+/**
+ *
+ */
+const quux = async function () {}
+
+/**
+ *
+ */
+const quux = async () => {}
+
 /** foo class */
 class foo {
   /** foo constructor */
@@ -4875,6 +4930,13 @@ class foo {
 }
 
 export default foo;
+
+/**
+ *
+ */
+function quux () {
+}
+// Options: [{"forceReturnsWithAsync":true}]
 ````
 
 

src/iterateJsdoc.js

@@ -145,8 +145,12 @@ const curryUtils = (
     return jsdocUtils.hasDefinedTypeReturnTag(tag);
   };
 
-  utils.hasReturnValue = () => {
-    return jsdocUtils.hasReturnValue(node, context);
+  utils.hasReturnValue = (ignoreAsync = false) => {
+    return jsdocUtils.hasReturnValue(node, context, ignoreAsync);
+  };
+
+  utils.isAsync = () => {
+    return node.async;
   };
 
   utils.getTags = (tagName) => {

src/jsdocUtils.js

@@ -372,27 +372,27 @@ const lookupTable = {
     is (node) {
       return node.type === 'FunctionExpression';
     },
-    check (node, context) {
-      return node.async || lookupTable.BlockStatement.check(node.body, context);
+    check (node, context, ignoreAsync) {
+      return !ignoreAsync && node.async || lookupTable.BlockStatement.check(node.body, context);
     }
   },
   ArrowFunctionExpression: {
     is (node) {
       return node.type === 'ArrowFunctionExpression';
     },
-    check (node, context) {
+    check (node, context, ignoreAsync) {
       // An expression always has a return value.
       return node.expression ||
-        node.async ||
+        !ignoreAsync && node.async ||
         lookupTable.BlockStatement.check(node.body, context);
     }
   },
   FunctionDeclaration: {
     is (node) {
       return node.type === 'FunctionDeclaration';
     },
-    check (node, context) {
-      return node.async || lookupTable.BlockStatement.check(node.body, context);
+    check (node, context, ignoreAsync) {
+      return !ignoreAsync && node.async || lookupTable.BlockStatement.check(node.body, context);
     }
   },
   '@default': {
@@ -431,14 +431,17 @@ const lookupTable = {
  *
  * @param {Object} node
  *   the node which should be checked.
+ * @param {Object} context
+ * @param {boolean} ignoreAsync
+ *   ignore implicit async return.
  * @returns {boolean}
  *   true in case the code returns a return value
  */
-const hasReturnValue = (node, context) => {
+const hasReturnValue = (node, context, ignoreAsync) => {
   // Loop through all of our entry points
   for (const item of ENTRY_POINTS) {
     if (lookupTable[item].is(node)) {
-      return lookupTable[item].check(node, context);
+      return lookupTable[item].check(node, context, ignoreAsync);
     }
   }
 

src/rules/requireReturns.js

@@ -43,6 +43,7 @@ const canSkip = (utils) => {
 export default iterateJsdoc(({
   report,
   utils,
+  context,
   settings
 }) => {
   // A preflight check. We do not need to run a deep check
@@ -51,6 +52,8 @@ export default iterateJsdoc(({
     return;
   }
 
+  const options = context.options[0] || {};
+
   const tagName = utils.getPreferredTagName('returns');
   const tags = utils.getTags(tagName);
 
@@ -62,7 +65,7 @@ export default iterateJsdoc(({
   const [tag] = tags;
   const missingReturnTag = typeof tag === 'undefined' || tag === null;
   if (missingReturnTag &&
-    (utils.hasReturnValue() || settings.forceRequireReturn)
+    ((utils.isAsync() && !utils.hasReturnValue(true) ? Boolean(options.forceReturnsWithAsync) : utils.hasReturnValue()) || settings.forceRequireReturn)
   ) {
     report('Missing JSDoc @' + tagName + ' declaration.');
   }