Merge pull request #217 from brettz9/reworkRequireReturns

Rework require returns

Author: brettz9

README.md

@@ -2515,7 +2515,7 @@ The following patterns are considered problems:
 function quux (foo) {
 
 }
-// Message: Present JSDoc @returns declaration but not available return expression in function.
+// Message: JSDoc @returns declaration present but return expression not available in function.
 
 /**
  * @return
@@ -2524,13 +2524,13 @@ function quux (foo) {
 
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}
-// Message: Present JSDoc @return declaration but not available return expression in function.
+// Message: JSDoc @return declaration present but return expression not available in function.
 
 /**
  * @returns
  */
 const quux = () => {}
-// Message: Present JSDoc @returns declaration but not available return expression in function.
+// Message: JSDoc @returns declaration present but return expression not available in function.
 
 /**
  * @returns {undefined} Foo.
@@ -2541,6 +2541,17 @@ function quux () {
   return foo;
 }
 // Message: Found more than one @returns declaration.
+
+const language = {
+  /**
+   * @param {string} name
+   * @returns {string}
+   */
+  get name() {
+    this._name = name;
+  }
+}
+// Message: JSDoc @returns declaration present but return expression not available in function.
 ````
 
 The following patterns are not considered problems:
@@ -2555,15 +2566,15 @@ function quux () {
 }
 
 /**
- * @returns {void} Foo.
+ * @returns {string} Foo.
  */
 function quux () {
 
   return foo;
 }
 
 /**
- * @returns {undefined} Foo.
+ * @returns {string} Foo.
  */
 function quux () {
 
@@ -2599,7 +2610,12 @@ async function quux() {}
 /**
  * @returns {Promise<void>}
  */
-async () => {}
+const quux = async function () {}
+
+/**
+ * @returns {Promise<void>}
+ */
+const quux = async () => {}
 
 /**
  * @returns Foo.
@@ -2608,6 +2624,33 @@ async () => {}
 function quux () {
   throw new Error('must be implemented by subclass!');
 }
+
+/**
+ * @returns Foo.
+ * @virtual
+ */
+function quux () {
+  throw new Error('must be implemented by subclass!');
+}
+
+/**
+ * @returns Foo.
+ * @constructor
+ */
+function quux () {
+}
+
+/**
+ * @returns {undefined} Foo.
+ */
+function quux () {
+}
+
+/**
+ * @returns {void} Foo.
+ */
+function quux () {
+}
 ````
 
 
@@ -2662,6 +2705,42 @@ function quux (foo) {
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"returns":"return"}}}
 // Message: Missing JSDoc @return declaration.
+
+/**
+ *
+ */
+async function quux() {}
+// Message: Missing JSDoc @returns declaration.
+
+/**
+ *
+ */
+const quux = async function () {}
+// Message: Missing JSDoc @returns declaration.
+
+/**
+ *
+ */
+const quux = async () => {}
+// Message: Missing JSDoc @returns declaration.
+
+/**
+ *
+ */
+function quux () {
+}
+// Settings: {"jsdoc":{"forceRequireReturn":true}}
+// Message: Missing JSDoc @returns declaration.
+
+const language = {
+  /**
+   * @param {string} name
+   */
+  get name() {
+    return this._name;
+  }
+}
+// Message: Missing JSDoc @returns declaration.
 ````
 
 The following patterns are not considered problems:
@@ -2710,16 +2789,121 @@ const quux = (bar) => bar.filter(({ corge }) => corge())
 function quux (foo) {
 }
 
+/**
+ * @implements
+ */
+function quux (foo) {
+}
+
+/**
+ * @override
+ */
+function quux (foo) {
+}
+
+/**
+ * @constructor
+ */
+function quux (foo) {
+}
+
 /**
  * @override
  */
 function quux (foo) {
+
+  return foo;
+}
+
+/**
+ * @class
+ */
+function quux (foo) {
+
 }
 
 /**
  * @constructor
  */
 function quux (foo) {
+
+}
+
+/**
+ * @returns {Object}
+ */
+function quux () {
+
+  return {a: foo};
+}
+
+/**
+ * @returns {Object}
+ */
+const quux = () => ({a: foo});
+
+/**
+ * @returns {Object}
+ */
+const quux = () => {
+  return {a: foo}
+};
+
+/**
+ * @returns {void}
+ */
+function quux () {
+}
+
+/**
+ * @returns {void}
+ */
+const quux = () => {
+
+}
+
+/**
+ * @returns {undefined}
+ */
+function quux () {
+}
+
+/**
+ * @returns {undefined}
+ */
+const quux = () => {
+
+}
+
+/**
+ *
+ */
+function quux () {
+}
+
+/**
+ *
+ */
+const quux = () => {
+
+}
+
+class Foo {
+  /**
+   *
+   */
+  constructor () {
+  }
+}
+// Settings: {"jsdoc":{"forceRequireReturn":true}}
+
+const language = {
+  /**
+   * @param {string} name
+   */
+  set name(name) {
+    this._name = name;
+  }
 }
 ````
 

src/iterateJsdoc.js

@@ -41,8 +41,10 @@ const curryUtils = (
   allowImplementsWithoutParam,
   allowAugmentsExtendsWithoutParam,
   checkSeesForNamepaths,
+  forceRequireReturn,
   ancestors,
-  sourceCode
+  sourceCode,
+  context
 ) => {
   const utils = {};
 
@@ -58,6 +60,10 @@ const curryUtils = (
     return node.parent && node.parent.kind === 'constructor';
   };
 
+  utils.isSetter = () => {
+    return node.parent.kind === 'set';
+  };
+
   utils.getJsdocParameterNamesDeep = () => {
     return jsdocUtils.getJsdocParameterNamesDeep(jsdoc, utils.getPreferredTagName('param'));
   };
@@ -143,6 +149,32 @@ const curryUtils = (
     ], tag.tag);
   };
 
+  utils.isArrowExpression = () => {
+    return node.type === 'ArrowFunctionExpression' && node.expression;
+  };
+
+  utils.hasDefinedTypeReturnTag = (tag) => {
+    return jsdocUtils.hasDefinedTypeReturnTag(tag);
+  };
+
+  utils.hasReturnValue = () => {
+    return jsdocUtils.hasReturnValue(node, context);
+  };
+
+  utils.getTags = (tagName) => {
+    if (!jsdoc.tags) {
+      return [];
+    }
+
+    return jsdoc.tags.filter((item) => {
+      return item.tag === tagName;
+    });
+  };
+
+  utils.isForceRequireReturn = () => {
+    return forceRequireReturn;
+  };
+
   utils.getClassJsdocNode = () => {
     const greatGrandParent = ancestors.slice(-3)[0];
     const greatGrandParentValue = greatGrandParent && sourceCode.getFirstToken(greatGrandParent).value;
@@ -210,6 +242,7 @@ export default (iterator, options) => {
       const allowImplementsWithoutParam = Boolean(_.get(context, 'settings.jsdoc.allowImplementsWithoutParam'));
       const allowAugmentsExtendsWithoutParam = Boolean(_.get(context, 'settings.jsdoc.allowAugmentsExtendsWithoutParam'));
       const checkSeesForNamepaths = Boolean(_.get(context, 'settings.jsdoc.checkSeesForNamepaths'));
+      const forceRequireReturn = Boolean(_.get(context, 'settings.jsdoc.forceRequireReturn'));
 
       const checkJsdoc = (node) => {
         const jsdocNode = sourceCode.getJSDocComment(node);
@@ -277,6 +310,7 @@ export default (iterator, options) => {
           allowImplementsWithoutParam,
           allowAugmentsExtendsWithoutParam,
           checkSeesForNamepaths,
+          forceRequireReturn,
           ancestors,
           sourceCode
         );