fix(require-returns-check, require-yields-check): avoid never being reported

Author: brettz9

README.md

@@ -16637,6 +16637,19 @@ function quux () {
   return undefined;
 }
 
+/**
+ * @returns {never} Foo.
+ */
+function quux () {
+}
+
+/**
+ * @returns {never} Foo.
+ */
+function quux () {
+  return undefined;
+}
+
 /**
  * @returns {void} Foo.
  */
@@ -19583,6 +19596,12 @@ function * quux () {
 function * quux () {
 }
 
+/**
+ * @yields {never} Foo.
+ */
+function * quux () {
+}
+
 /**
  * @yields {void} Foo.
  */
@@ -19789,6 +19808,14 @@ function * quux (foo) {
   const a = yield 5;
 }
 // "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
+
+/**
+ * @next {never}
+ */
+function * quux (foo) {
+
+}
+// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
 ````
 
 

src/rules/requireReturnsCheck.js

@@ -66,10 +66,19 @@ export default iterateJsdoc(({
     return;
   }
 
+  const [tag] = tags;
+
   // In case a return value is declared in JSDoc, we also expect one in the code.
-  if ((reportMissingReturnForUndefinedTypes || utils.hasDefinedTypeTag(tags[0])) && !utils.hasValueOrExecutorHasNonEmptyResolveValue(
-    exemptAsync,
-  ) && (!exemptGenerators || !node.generator)) {
+  if (
+    tag.type.trim() !== 'never' &&
+    (
+      reportMissingReturnForUndefinedTypes ||
+      utils.hasDefinedTypeTag(tag)
+    ) &&
+    !utils.hasValueOrExecutorHasNonEmptyResolveValue(
+      exemptAsync,
+    ) && (!exemptGenerators || !node.generator)
+  ) {
     report(`JSDoc @${tagName} declaration present but return expression not available in function.`);
   }
 }, {

src/rules/requireYieldsCheck.js

@@ -71,6 +71,10 @@ export default iterateJsdoc(({
   );
   if (preferredYieldTagName) {
     const shouldReportYields = () => {
+      if (yieldTag.type.trim() === 'never') {
+        return false;
+      }
+
       if (checkGeneratorsOnly && !utils.isGenerator()) {
         return true;
       }
@@ -90,6 +94,10 @@ export default iterateJsdoc(({
     );
     if (preferredNextTagName) {
       const shouldReportNext = () => {
+        if (nextTag.type.trim() === 'never') {
+          return false;
+        }
+
         if (checkGeneratorsOnly && !utils.isGenerator()) {
           return true;
         }

test/rules/assertions/requireReturnsCheck.js

@@ -519,6 +519,25 @@ export default {
           }
       `,
     },
+    {
+      code: `
+          /**
+           * @returns {never} Foo.
+           */
+          function quux () {
+          }
+      `,
+    },
+    {
+      code: `
+          /**
+           * @returns {never} Foo.
+           */
+          function quux () {
+            return undefined;
+          }
+      `,
+    },
     {
       code: `
           /**

test/rules/assertions/requireYieldsCheck.js

@@ -440,6 +440,15 @@ export default {
           }
       `,
     },
+    {
+      code: `
+          /**
+           * @yields {never} Foo.
+           */
+          function * quux () {
+          }
+      `,
+    },
     {
       code: `
           /**
@@ -719,5 +728,18 @@ export default {
         next: true,
       }],
     },
+    {
+      code: `
+          /**
+           * @next {never}
+           */
+          function * quux (foo) {
+
+          }
+      `,
+      options: [{
+        next: true,
+      }],
+    },
   ],
 };