- require-returns-check: If a return is documented, allow @class and @interface (as with @constructor) to ignore reporting a missing return in body as constructors implicitly return the class; for testing, add getter check

- `require-returns`: Allow presence of `@interface` to avoid need for `@returns` (as `@interface implies a class`); Allow presence of ES setter to avoid need for `@returns` as setters don't return

Author: brettz9

src/iterateJsdoc.js

@@ -60,6 +60,10 @@ const curryUtils = (
     return node.parent && node.parent.kind === 'constructor';
   };
 
+  utils.isSetter = () => {
+    return functionNode.parent.kind === 'set';
+  };
+
   utils.getJsdocParameterNamesDeep = () => {
     return jsdocUtils.getJsdocParameterNamesDeep(jsdoc, utils.getPreferredTagName('param'));
   };

src/rules/requireReturns.js

@@ -30,12 +30,20 @@ const canSkip = (utils) => {
     'class',
     'constructor',
 
+    // This seems to imply a class as well
+    'interface',
+
     // While we may, in a future rule, err in the case of (regular) functions
     //  using @implements (see https://github.com/gajus/eslint-plugin-jsdoc/issues/201 ),
     //  this should not error for those using the tag to indicate implementation of
     //  a particular function signature
     'implements'
-  ]) || utils.isConstructor();
+  ]) ||
+    utils.isConstructor() ||
+
+    // Though ESLint avoided getters: https://github.com/eslint/eslint/blob/master/lib/rules/valid-jsdoc.js#L435
+    //  ... getters seem that they should, unlike setters, always return:
+    utils.isSetter();
 };
 
 export default iterateJsdoc(({

src/rules/requireReturnsCheck.js

@@ -1,33 +1,28 @@
 import iterateJsdoc from '../iterateJsdoc';
 
-const canSkip = (utils, node) => {
+const canSkip = (utils) => {
   return utils.hasATag([
     // An abstract function is by definition incomplete
-    // so it is perfectly fine if the return is missing.
+    // so it is perfectly fine if a return is documented but
+    // not present within the function.
     // A subclass may inherit the doc and implement the
     // missing return.
     'abstract',
     'virtual',
 
-    // A constructor function returns `this` by default
-    'constructor'
-  ]) ||
-
-    utils.isConstructor() ||
-
-    // Implicit return like `() => foo` is ok
-    utils.isArrowExpression() ||
-
-    // Async function always returns a `Promise`
-    node.async;
+    // A constructor function returns `this` by default, so may be `@returns`
+    //   tag indicating this but no explicit return
+    'class',
+    'constructor',
+    'interface'
+  ]) || utils.isConstructor();
 };
 
 export default iterateJsdoc(({
   report,
-  node,
   utils
 }) => {
-  if (canSkip(utils, node)) {
+  if (canSkip(utils)) {
     return;
   }
 

test/rules/assertions/requireReturns.js

@@ -155,6 +155,24 @@ export default {
           forceRequireReturn: true
         }
       }
+    },
+    {
+      code: `
+      const language = {
+        /**
+         * @param {string} name
+         */
+        get name() {
+          return this._name;
+        }
+      }
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Missing JSDoc @returns declaration.'
+        }
+      ]
     }
   ],
   valid: [
@@ -378,6 +396,18 @@ export default {
           forceRequireReturn: true
         }
       }
+    },
+    {
+      code: `
+      const language = {
+        /**
+         * @param {string} name
+         */
+        set name(name) {
+          this._name = name;
+        }
+      }
+      `
     }
   ]
 };

test/rules/assertions/requireReturnsCheck.js

@@ -70,6 +70,25 @@ export default {
           message: 'Found more than one @returns declaration.'
         }
       ]
+    },
+    {
+      code: `
+      const language = {
+        /**
+         * @param {string} name
+         * @returns {string}
+         */
+        get name() {
+          this._name = name;
+        }
+      }
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'JSDoc @returns declaration present but return expression not available in function.'
+        }
+      ]
     }
   ],
   valid: [