fix(require-returns): should only report errors with async function…

…s when `forceReturnsWithAsync` is set

This also clarifies the `forceReturnsWithAsync` options and adds further test cases

.README/rules/require-returns.md

@@ -12,7 +12,12 @@ Will also report if multiple `@returns` tags are present.
   `@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. You can force all `async` functions to require return statements by setting `forceReturnsWithAsync` to `true` on the options object. This may be useful as an `async` function will always return a `Promise`, even if the `Promise` returns void. 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`.
 
 ```js
 'jsdoc/require-returns': ['error', {forceReturnsWithAsync: true}]

README.md

@@ -8496,7 +8496,12 @@ Will also report if multiple `@returns` tags are present.
   `@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. You can force all `async` functions to require return statements by setting `forceReturnsWithAsync` to `true` on the options object. This may be useful as an `async` function will always return a `Promise`, even if the `Promise` returns void. 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`.
 
 ```js
 'jsdoc/require-returns': ['error', {forceReturnsWithAsync: true}]
@@ -8646,6 +8651,24 @@ function quux (foo) {
 }
 // Options: [{"exemptedBy":["notPresent"]}]
 // Message: Missing JSDoc @returns declaration.
+
+/**
+ * @param {array} a
+ */
+async function foo(a) {
+  return;
+}
+// Options: [{"forceReturnsWithAsync":true}]
+// Message: Missing JSDoc @returns declaration.
+
+/**
+ * @param {array} a
+ */
+async function foo(a) {
+  return Promise.all(a);
+}
+// Options: [{"forceReturnsWithAsync":true}]
+// Message: Missing JSDoc @returns declaration.
 ````
 
 The following patterns are not considered problems:
@@ -8914,6 +8937,20 @@ function quux () {
 
 }
 // Options: [{"exemptedBy":["type"]}]
+
+/**
+ * @param {array} a
+ */
+async function foo(a) {
+  return Promise.all(a);
+}
+
+/**
+ * @param {array} a
+ */
+async function foo(a) {
+  return;
+}
 ````
 
 

src/rules/requireReturns.js

@@ -82,11 +82,13 @@ export default iterateJsdoc(({
       return true;
     }
 
-    if (forceReturnsWithAsync && utils.isAsync() && !utils.hasReturnValue()) {
+    const isAsync = utils.isAsync();
+
+    if (forceReturnsWithAsync && isAsync) {
       return true;
     }
 
-    return utils.hasReturnValue();
+    return !isAsync && utils.hasReturnValue();
   };
 
   if (shouldReport()) {

test/rules/assertions/requireReturns.js

@@ -307,6 +307,50 @@ export default {
         },
       ],
     },
+    {
+      code: `
+      /**
+       * @param {array} a
+       */
+      async function foo(a) {
+        return;
+      }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @returns declaration.',
+        },
+      ],
+      options: [{
+        forceReturnsWithAsync: true,
+      }],
+      parserOptions: {
+        ecmaVersion: 8,
+      },
+    },
+    {
+      code: `
+      /**
+       * @param {array} a
+       */
+      async function foo(a) {
+        return Promise.all(a);
+      }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @returns declaration.',
+        },
+      ],
+      options: [{
+        forceReturnsWithAsync: true,
+      }],
+      parserOptions: {
+        ecmaVersion: 8,
+      },
+    },
   ],
   valid: [
     {
@@ -725,5 +769,31 @@ export default {
         },
       ],
     },
+    {
+      code: `
+      /**
+       * @param {array} a
+       */
+      async function foo(a) {
+        return Promise.all(a);
+      }
+      `,
+      parserOptions: {
+        ecmaVersion: 8,
+      },
+    },
+    {
+      code: `
+      /**
+       * @param {array} a
+       */
+      async function foo(a) {
+        return;
+      }
+      `,
+      parserOptions: {
+        ecmaVersion: 8,
+      },
+    },
   ],
 };