feat(require-returns): add forceReturnsWithAsync

Async functions implicitly returning Promise<void> are now behind the forceReturnsWithAsync (or forceRequireReturn) setting.

Author: AndrewLeedham

.README/README.md

@@ -296,6 +296,10 @@ only (e.g., to match `Array` if the type is `Array` vs. `Array.<string>`).
   `@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.
+* `settings.jsdoc.forceReturnsWithAsync` - Set to `true` to always insist on
+  `@returns` documentation regardless of implicit or explicit `return`'s
+  in an async function. May be desired to flag that a project is aware of a
+  `Promise<void>` return.
 
 ### Settings to Configure `require-example`
 

.README/rules/require-returns.md

@@ -7,6 +7,6 @@ Requires returns are documented.
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`returns`|
 |Aliases|`return`|
-|Settings|`forceRequireReturn`|
+|Settings|`forceRequireReturn`, `forceReturnsWithAsync`|
 
 <!-- assertions requireReturns -->

README.md

@@ -351,6 +351,10 @@ only (e.g., to match `Array` if the type is `Array` vs. `Array.<string>`).
   `@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.
+* `settings.jsdoc.forceReturnsWithAsync` - Set to `true` to always insist on
+  `@returns` documentation regardless of implicit or explicit `return`'s
+  in an async function. May be desired to flag that a project is aware of a
+  `Promise<void>` return.
 
 <a name="eslint-plugin-jsdoc-settings-settings-to-configure-require-example"></a>
 ### Settings to Configure <code>require-example</code>
@@ -4569,7 +4573,7 @@ Requires returns are documented.
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`returns`|
 |Aliases|`return`|
-|Settings|`forceRequireReturn`|
+|Settings|`forceRequireReturn`, `forceReturnsWithAsync`|
 
 The following patterns are considered problems:
 
@@ -4616,19 +4620,23 @@ 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.
 
 /**
@@ -4648,6 +4656,14 @@ const language = {
   }
 }
 // Message: Missing JSDoc @returns declaration.
+
+/**
+ *
+ */
+async function quux () {
+}
+// Settings: {"jsdoc":{"forceReturnsWithAsync":true}}
+// Message: Missing JSDoc @returns declaration.
 ````
 
 The following patterns are not considered problems:
@@ -4857,6 +4873,35 @@ function quux () {
 }
 // Settings: {"jsdoc":{"forceRequireReturn":true}}
 
+/**
+ * @returns {Promise}
+ */
+async function quux () {
+}
+// Settings: {"jsdoc":{"forceRequireReturn":true}}
+
+/**
+ * @returns {Promise}
+ */
+async function quux () {
+}
+// Settings: {"jsdoc":{"forceReturnsWithAsync":true}}
+
+/**
+ *
+ */
+async function quux () {}
+
+/**
+ *
+ */
+const quux = async function () {}
+
+/**
+ *
+ */
+const quux = async () => {}
+
 /** foo class */
 class foo {
   /** foo constructor */

src/iterateJsdoc.js

@@ -46,6 +46,7 @@ const curryUtils = (
   allowAugmentsExtendsWithoutParam,
   checkSeesForNamepaths,
   forceRequireReturn,
+  forceReturnsWithAsync,
   avoidExampleOnConstructors,
   ancestors,
   sourceCode,
@@ -199,8 +200,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) => {
@@ -213,6 +218,10 @@ const curryUtils = (
     return forceRequireReturn;
   };
 
+  utils.isForceReturnsWithAsync = () => {
+    return forceReturnsWithAsync;
+  };
+
   utils.filterTags = (filter) => {
     return (jsdoc.tags || []).filter(filter);
   };
@@ -312,6 +321,7 @@ export default (iterator, opts = {}) => {
 
       // `require-returns` only
       const forceRequireReturn = Boolean(_.get(context, 'settings.jsdoc.forceRequireReturn'));
+      const forceReturnsWithAsync = Boolean(_.get(context, 'settings.jsdoc.forceReturnsWithAsync'));
 
       // `require-example` only
       const avoidExampleOnConstructors = Boolean(_.get(context, 'settings.jsdoc.avoidExampleOnConstructors'));
@@ -388,6 +398,7 @@ export default (iterator, opts = {}) => {
           allowAugmentsExtendsWithoutParam,
           checkSeesForNamepaths,
           forceRequireReturn,
+          forceReturnsWithAsync,
           avoidExampleOnConstructors,
           ancestors,
           sourceCode

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

@@ -58,7 +58,7 @@ export default iterateJsdoc(({
   const [tag] = tags;
   const missingReturnTag = typeof tag === 'undefined' || tag === null;
   if (missingReturnTag &&
-    (utils.hasReturnValue() || utils.isForceRequireReturn())
+    ((utils.isAsync() && !utils.hasReturnValue(true) ? utils.isForceReturnsWithAsync() : utils.hasReturnValue()) || utils.isForceRequireReturn())
   ) {
     report('Missing JSDoc @' + tagName + ' declaration.');
   }

test/rules/assertions/requireReturns.js

@@ -90,7 +90,8 @@ export default {
           /**
            *
            */
-          async function quux() {}
+          async function quux() {
+          }
       `,
       errors: [
         {
@@ -100,6 +101,11 @@ export default {
       ],
       parserOptions: {
         ecmaVersion: 8
+      },
+      settings: {
+        jsdoc: {
+          forceRequireReturn: true
+        }
       }
     },
     {
@@ -117,6 +123,11 @@ export default {
       ],
       parserOptions: {
         ecmaVersion: 8
+      },
+      settings: {
+        jsdoc: {
+          forceRequireReturn: true
+        }
       }
     },
     {
@@ -134,6 +145,11 @@ export default {
       ],
       parserOptions: {
         ecmaVersion: 8
+      },
+      settings: {
+        jsdoc: {
+          forceRequireReturn: true
+        }
       }
     },
     {
@@ -173,6 +189,29 @@ export default {
           message: 'Missing JSDoc @returns declaration.'
         }
       ]
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          async function quux () {
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @returns declaration.'
+        }
+      ],
+      parserOptions: {
+        ecmaVersion: 8
+      },
+      settings: {
+        jsdoc: {
+          forceReturnsWithAsync: true
+        }
+      }
     }
   ],
   valid: [
@@ -487,6 +526,73 @@ export default {
         }
       }
     },
+    {
+      code: `
+          /**
+           * @returns {Promise}
+           */
+          async function quux () {
+          }
+      `,
+      parserOptions: {
+        ecmaVersion: 8
+      },
+      settings: {
+        jsdoc: {
+          forceRequireReturn: true
+        }
+      }
+    },
+    {
+      code: `
+          /**
+           * @returns {Promise}
+           */
+          async function quux () {
+          }
+      `,
+      parserOptions: {
+        ecmaVersion: 8
+      },
+      settings: {
+        jsdoc: {
+          forceReturnsWithAsync: true
+        }
+      }
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          async function quux () {}
+      `,
+      parserOptions: {
+        ecmaVersion: 8
+      }
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          const quux = async function () {}
+      `,
+      parserOptions: {
+        ecmaVersion: 8
+      }
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          const quux = async () => {}
+      `,
+      parserOptions: {
+        ecmaVersion: 8
+      }
+    },
     {
       code: `
       /** foo class */