fix: stop reporting async function (unless with `forceReturnsWithAs…

…ync`) or Promise return with void type parameter; fixes #845
gajus · Feb 28, 2022 · 509baf9 · 509baf9
1 parent ef68427
commit 509baf9
Show file tree

Hide file tree

Showing 4 changed files with 113 additions and 29 deletions.
diff --git a/README.md b/README.md
@@ -17700,14 +17700,6 @@ class quux {
 // "jsdoc/require-returns": ["error"|"warn", {"contexts":["any"],"forceRequireReturn":true}]
 // Message: Missing JSDoc @returns declaration.
 
-/**
- * @param {array} a
- */
-async function foo(a) {
-  return Promise.all(a);
-}
-// Message: Missing JSDoc @returns declaration.
-
 /**
  *
  */
@@ -18005,6 +17997,21 @@ export function f(): string {
 }
 // "jsdoc/require-returns": ["error"|"warn", {"contexts":[":not(BlockStatement) > FunctionDeclaration","MethodDefinition","TSMethodSignature","TSPropertySignature > TSTypeAnnotation > TSFunctionType"]}]
 // Message: Missing JSDoc @returns declaration.
+
+/**
+ * @param ms time in millis
+ */
+export const sleep = (ms: number) =>
+  new Promise<string>((res) => setTimeout(res, ms));
+// Message: Missing JSDoc @returns declaration.
+
+/**
+ * @param ms time in millis
+ */
+export const sleep = (ms: number) => {
+  return new Promise<string>((res) => setTimeout(res, ms));
+};
+// Message: Missing JSDoc @returns declaration.
 ````
 
 The following patterns are not considered problems:
@@ -18488,6 +18495,26 @@ function quux () {
 async function foo() {
   return new Promise(resolve => resolve());
 }
+
+/**
+ * @param {array} a
+ */
+async function foo(a) {
+  return Promise.all(a);
+}
+
+/**
+ * @param ms time in millis
+ */
+export const sleep = (ms: number) =>
+  new Promise<void>((res) => setTimeout(res, ms));
+
+/**
+ * @param ms time in millis
+ */
+export const sleep = (ms: number) => {
+  return new Promise<void>((res) => setTimeout(res, ms));
+};
 ````
 
 

diff --git a/src/jsdocUtils.js b/src/jsdocUtils.js
@@ -681,6 +681,10 @@ const isNewPromiseExpression = (node) => {
     node.callee.name === 'Promise';
 };
 
+const isVoidPromise = (node) => {
+  return node.typeParameters?.params?.[0]?.type === 'TSVoidKeyword';
+};
+
 /**
  * @callback PromiseFilter
  * @param {object} node
@@ -712,7 +716,8 @@ const hasReturnValue = (node, promFilter) => {
   case 'FunctionExpression':
   case 'FunctionDeclaration':
   case 'ArrowFunctionExpression': {
-    return node.expression || hasReturnValue(node.body, promFilter);
+    return node.expression && (!isNewPromiseExpression(node.body) || !isVoidPromise(node?.body)) ||
+      hasReturnValue(node.body, promFilter);
   }
 
   case 'BlockStatement': {
@@ -988,6 +993,10 @@ const hasValueOrExecutorHasNonEmptyResolveValue = (node, anyPromiseAsReturn) =>
       return true;
     }
 
+    if (isVoidPromise(prom)) {
+      return false;
+    }
+
     const [
       {
         params,

diff --git a/src/rules/requireReturns.js b/src/rules/requireReturns.js
@@ -90,7 +90,7 @@ export default iterateJsdoc(({
       return true;
     }
 
-    return iteratingFunction && utils.hasValueOrExecutorHasNonEmptyResolveValue(
+    return !isAsync && iteratingFunction && utils.hasValueOrExecutorHasNonEmptyResolveValue(
       forceReturnsWithAsync,
     );
   };

diff --git a/test/rules/assertions/requireReturns.js b/test/rules/assertions/requireReturns.js
@@ -570,25 +570,6 @@ export default {
         },
       ],
     },
-    {
-      code: `
-      /**
-       * @param {array} a
-       */
-      async function foo(a) {
-        return Promise.all(a);
-      }
-      `,
-      errors: [
-        {
-          line: 2,
-          message: 'Missing JSDoc @returns declaration.',
-        },
-      ],
-      parserOptions: {
-        ecmaVersion: 8,
-      },
-    },
     {
       code: `
           /**
@@ -1657,6 +1638,39 @@ export default {
       ],
       parser: require.resolve('@typescript-eslint/parser'),
     },
+    {
+      code: `
+        /**
+         * @param ms time in millis
+         */
+        export const sleep = (ms: number) =>
+          new Promise<string>((res) => setTimeout(res, ms));
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @returns declaration.',
+        },
+      ],
+      parser: require.resolve('@typescript-eslint/parser'),
+    },
+    {
+      code: `
+        /**
+         * @param ms time in millis
+         */
+        export const sleep = (ms: number) => {
+          return new Promise<string>((res) => setTimeout(res, ms));
+        };
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc @returns declaration.',
+        },
+      ],
+      parser: require.resolve('@typescript-eslint/parser'),
+    },
   ],
   valid: [
     {
@@ -2493,5 +2507,39 @@ export default {
       ],
       parser: require.resolve('@typescript-eslint/parser'),
     },
+    {
+      code: `
+      /**
+       * @param {array} a
+       */
+      async function foo(a) {
+        return Promise.all(a);
+      }
+      `,
+      parserOptions: {
+        ecmaVersion: 8,
+      },
+    },
+    {
+      code: `
+        /**
+         * @param ms time in millis
+         */
+        export const sleep = (ms: number) =>
+          new Promise<void>((res) => setTimeout(res, ms));
+      `,
+      parser: require.resolve('@typescript-eslint/parser'),
+    },
+    {
+      code: `
+        /**
+         * @param ms time in millis
+         */
+        export const sleep = (ms: number) => {
+          return new Promise<void>((res) => setTimeout(res, ms));
+        };
+      `,
+      parser: require.resolve('@typescript-eslint/parser'),
+    },
   ],
 };