fix(require-returns-check): checks that all branches of final node return; fixes #892

This release expressed as a reversion of a commit (bba377e) in order to fix the commit message to properly trigger a release.

Author: brettz9

.README/rules/require-returns-check.md

@@ -2,10 +2,11 @@
 
 Requires a return statement (or non-`undefined` Promise resolve value) in
 function bodies if a `@returns` tag (without a `void` or `undefined` type)
-is specified in the function's jsdoc comment.
+is specified in the function's JSDoc comment.
 
 Will also report `@returns {void}` and `@returns {undefined}` if `exemptAsync`
-is set to `false` no non-`undefined` returned or resolved value is found.
+is set to `false` and a non-`undefined` value is returned or a resolved value
+is found. Also reports if `@returns {never}` is discovered with a return value.
 
 Will also report if multiple `@returns` tags are present.
 

README.md

@@ -17208,10 +17208,11 @@ The following patterns are not considered problems:
 
 Requires a return statement (or non-`undefined` Promise resolve value) in
 function bodies if a `@returns` tag (without a `void` or `undefined` type)
-is specified in the function's jsdoc comment.
+is specified in the function's JSDoc comment.
 
 Will also report `@returns {void}` and `@returns {undefined}` if `exemptAsync`
-is set to `false` no non-`undefined` returned or resolved value is found.
+is set to `false` and a non-`undefined` value is returned or a resolved value
+is found. Also reports if `@returns {never}` is discovered with a return value.
 
 Will also report if multiple `@returns` tags are present.
 
@@ -17437,6 +17438,17 @@ export function readFixture(path: string): void;
 export function readFixture(path: string);
 // Message: JSDoc @returns declaration present but return expression not available in function.
 
+/**
+ * @returns {SomeType}
+ */
+function quux (path) {
+  if (true) {
+    return;
+  }
+  return 15;
+};
+// Message: JSDoc @returns declaration present but return expression not available in function.
+
 /**
  * Reads a test fixture.
  *
@@ -17449,6 +17461,87 @@ export function readFixture(path: string): void {
   return;
 };
 // Message: JSDoc @returns declaration present but return expression not available in function.
+
+/**
+ * @returns {true}
+ */
+function quux () {
+  if (true) {
+    return true;
+  }
+}
+// Message: JSDoc @returns declaration present but return expression not available in function.
+
+/**
+ * @returns {true}
+ */
+function quux () {
+  if (true) {
+  } else {
+    return;
+  }
+}
+// Message: JSDoc @returns declaration present but return expression not available in function.
+
+/**
+ * @returns {true}
+ */
+function quux (someVar) {
+  switch (someVar) {
+  case 1:
+    return true;
+  case 2:
+    return;
+  }
+}
+// Message: JSDoc @returns declaration present but return expression not available in function.
+
+/**
+ * @returns {boolean}
+ */
+const quux = (someVar) => {
+  if (someVar) {
+    return true;
+  }
+};
+// Message: JSDoc @returns declaration present but return expression not available in function.
+
+/**
+ * @returns {true}
+ */
+function quux () {
+  try {
+    return true;
+  } catch (error) {
+  }
+}
+// Message: JSDoc @returns declaration present but return expression not available in function.
+
+/**
+ * @returns {true}
+ */
+function quux () {
+  try {
+    return true;
+  } catch (error) {
+    return true;
+  } finally {
+    return;
+  }
+}
+// Message: JSDoc @returns declaration present but return expression not available in function.
+
+/**
+ * @returns {true}
+ */
+function quux () {
+  try {
+  } catch (error) {
+  } finally {
+    return true;
+  }
+}
+// Message: JSDoc @returns declaration present but return expression not available in function.
 ````
 
 The following patterns are not considered problems:
@@ -17614,7 +17707,7 @@ function quux () {
     return true;
   } catch (err) {
   }
-  return;
+  return true;
 }
 
 /**
@@ -17625,15 +17718,15 @@ function quux () {
   } finally {
     return true;
   }
-  return;
+  return true;
 }
 
 /**
  * @returns {true}
  */
 function quux () {
   try {
-    return;
+    return true;
   } catch (err) {
   }
   return true;
@@ -17648,7 +17741,7 @@ function quux () {
   } catch (err) {
     return true;
   }
-  return;
+  return true;
 }
 
 /**
@@ -17659,7 +17752,7 @@ function quux () {
   case 'abc':
     return true;
   }
-  return;
+  return true;
 }
 
 /**
@@ -17668,7 +17761,7 @@ function quux () {
 function quux () {
   switch (true) {
   case 'abc':
-    return;
+    return true;
   }
   return true;
 }
@@ -17680,7 +17773,7 @@ function quux () {
   for (const i of abc) {
     return true;
   }
-  return;
+  return true;
 }
 
 /**
@@ -17696,7 +17789,7 @@ function quux () {
  * @returns {true}
  */
 function quux () {
-  for (let i=0; i<n; i+=1) {
+  for (const a of b) {
     return true;
   }
 }
@@ -17705,29 +17798,37 @@ function quux () {
  * @returns {true}
  */
 function quux () {
-  while(true) {
-    return true
+  loop: for (const a of b) {
+    return true;
   }
 }
 
 /**
  * @returns {true}
  */
 function quux () {
-  do {
+  for (let i=0; i<n; i+=1) {
+    return true;
+  }
+}
+
+/**
+ * @returns {true}
+ */
+function quux () {
+  while(true) {
     return true
   }
-  while(true)
 }
 
 /**
  * @returns {true}
  */
 function quux () {
-  if (true) {
-    return;
+  do {
+    return true
   }
-  return true;
+  while(true)
 }
 
 /**
@@ -17737,6 +17838,7 @@ function quux () {
   if (true) {
     return true;
   }
+  return true;
 }
 
 /**
@@ -17754,11 +17856,11 @@ function quux () {
  */
 function quux () {
   if (true) {
-    return;
+    return true;
   } else {
     return true;
   }
-  return;
+  return true;
 }
 
 /**
@@ -17865,6 +17967,32 @@ export function readFixture(path: string): Promise<Buffer> {
  * @returns {void} The file contents as buffer.
  */
 export function readFixture(path: string);
+
+/**
+ * @returns {SomeType}
+ */
+function quux (path) {
+  if (true) {
+    return 5;
+  }
+  return 15;
+};
+
+/**
+ * @returns {*} Foo.
+ */
+const quux = () => new Promise((resolve) => {
+  resolve(3);
+});
+
+/**
+ * @returns {*} Foo.
+ */
+const quux = function () {
+  return new Promise((resolve) => {
+    resolve(3);
+  });
+};
 ````
 
 

src/iterateJsdoc.js

@@ -680,8 +680,8 @@ const getUtils = (
     return jsdocUtils.hasDefinedTypeTag(tag);
   };
 
-  utils.hasValueOrExecutorHasNonEmptyResolveValue = (anyPromiseAsReturn) => {
-    return jsdocUtils.hasValueOrExecutorHasNonEmptyResolveValue(node, anyPromiseAsReturn);
+  utils.hasValueOrExecutorHasNonEmptyResolveValue = (anyPromiseAsReturn, allBranches) => {
+    return jsdocUtils.hasValueOrExecutorHasNonEmptyResolveValue(node, anyPromiseAsReturn, allBranches);
   };
 
   utils.hasYieldValue = () => {

src/rules/requireReturnsCheck.js

@@ -96,6 +96,7 @@ export default iterateJsdoc(({
     ) &&
     !utils.hasValueOrExecutorHasNonEmptyResolveValue(
       exemptAsync,
+      true,
     ) && (!exemptGenerators || !node.generator)
   ) {
     report(`JSDoc @${tagName} declaration present but return expression not available in function.`);