refactor: make forceReturnsWithAsync an option

Author: AndrewLeedham

.README/README.md

@@ -296,10 +296,6 @@ 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

@@ -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 maybe 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`, `forceReturnsWithAsync`|
+|Settings|`forceRequireReturn`|
+|Options|`forceReturnsWithAsync`|
 
 <!-- assertions requireReturns -->

README.md

@@ -351,10 +351,6 @@ 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>
@@ -4568,12 +4564,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 maybe 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`, `forceReturnsWithAsync`|
+|Settings|`forceRequireReturn`|
+|Options|`forceReturnsWithAsync`|
 
 The following patterns are considered problems:
 
@@ -4638,14 +4641,15 @@ const quux = async function () {}
 async function quux () {
 }
 // Settings: {"jsdoc":{"forceRequireReturn":true}}
+// Options: [{"forceReturnsWithAsync":true}]
 // Message: Missing JSDoc @returns declaration.
 
 /**
  *
  */
 function quux () {
 }
-// Settings: {"jsdoc":{"forceReturnsWithAsync":true}}
+// Options: [{"forceReturnsWithAsync":true}]
 // Message: Missing JSDoc @returns declaration.
 
 const language = {
@@ -4886,7 +4890,7 @@ async function quux () {
  */
 async function quux () {
 }
-// Settings: {"jsdoc":{"forceReturnsWithAsync":true}}
+// Options: [{"forceReturnsWithAsync":true}]
 
 /**
  *

src/iterateJsdoc.js

@@ -46,7 +46,6 @@ const curryUtils = (
   allowAugmentsExtendsWithoutParam,
   checkSeesForNamepaths,
   forceRequireReturn,
-  forceReturnsWithAsync,
   avoidExampleOnConstructors,
   ancestors,
   sourceCode,
@@ -218,10 +217,6 @@ const curryUtils = (
     return forceRequireReturn;
   };
 
-  utils.isForceReturnsWithAsync = () => {
-    return forceReturnsWithAsync;
-  };
-
   utils.filterTags = (filter) => {
     return (jsdoc.tags || []).filter(filter);
   };
@@ -321,7 +316,6 @@ 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'));
@@ -398,7 +392,6 @@ export default (iterator, opts = {}) => {
           allowAugmentsExtendsWithoutParam,
           checkSeesForNamepaths,
           forceRequireReturn,
-          forceReturnsWithAsync,
           avoidExampleOnConstructors,
           ancestors,
           sourceCode

src/rules/requireReturns.js

@@ -39,14 +39,17 @@ const canSkip = (utils) => {
 
 export default iterateJsdoc(({
   report,
-  utils
+  utils,
+  context
 }) => {
   // A preflight check. We do not need to run a deep check
   // in case the @returns comment is optional or undefined.
   if (canSkip(utils)) {
     return;
   }
 
+  const options = context.options[0] || {};
+
   const tagName = utils.getPreferredTagName('returns');
   const tags = utils.getTags(tagName);
 
@@ -58,7 +61,7 @@ export default iterateJsdoc(({
   const [tag] = tags;
   const missingReturnTag = typeof tag === 'undefined' || tag === null;
   if (missingReturnTag &&
-    ((utils.isAsync() && !utils.hasReturnValue(true) ? utils.isForceReturnsWithAsync() : utils.hasReturnValue()) || utils.isForceRequireReturn())
+    ((utils.isAsync() && !utils.hasReturnValue(true) ? Boolean(options.forceReturnsWithAsync) : utils.hasReturnValue()) || utils.isForceRequireReturn())
   ) {
     report('Missing JSDoc @' + tagName + ' declaration.');
   }

test/rules/assertions/requireReturns.js

@@ -135,8 +135,7 @@ export default {
           /**
            *
            */
-          async function quux () {
-          }
+          const quux = async () => {}
       `,
       errors: [
         {
@@ -169,7 +168,7 @@ export default {
       ],
       settings: {
         jsdoc: {
-          forceReturnsWithAsync: true
+          forceRequireReturn: true
         }
       }
     },
@@ -205,13 +204,11 @@ export default {
           message: 'Missing JSDoc @returns declaration.'
         }
       ],
+      options: [{
+        forceReturnsWithAsync: true
+      }],
       parserOptions: {
         ecmaVersion: 8
-      },
-      settings: {
-        jsdoc: {
-          forceReturnsWithAsync: true
-        }
       }
     }
   ],
@@ -552,13 +549,11 @@ export default {
           async function quux () {
           }
       `,
+      options: [{
+        forceReturnsWithAsync: true
+      }],
       parserOptions: {
         ecmaVersion: 8
-      },
-      settings: {
-        jsdoc: {
-          forceReturnsWithAsync: true
-        }
       }
     },
     {