feat: split require-returns in two rules and fix bug #142 (#147)

BREAKING CHANGE:

* require-returns rule is split into two rules:

Author: gajus

.README/README.md

@@ -28,6 +28,7 @@ This table maps the rules between `eslint-plugin-jsdoc` and `jscs-jsdoc`.
 | [`require-param-name`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-param-name) | N/A |
 | [`require-param-type`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-param-type) | [`requireParamTypes`](https://github.com/jscs-dev/jscs-jsdoc#requireparamtypes) |
 | [`require-returns`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns) | [`requireReturn`](https://github.com/jscs-dev/jscs-jsdoc#requirereturn) |
+| [`require-returns-check`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns-check) | [`requireReturn`](https://github.com/jscs-dev/jscs-jsdoc#requirereturncheck) |
 | [`require-returns-description`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns-description) | [`requireReturnDescription`](https://github.com/jscs-dev/jscs-jsdoc#requirereturndescription) |
 | [`require-returns-type`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns-type) | [`requireReturnTypes`](https://github.com/jscs-dev/jscs-jsdoc#requirereturntypes) |
 | [`valid-types`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-valid-types) | N/A |
@@ -85,6 +86,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/require-param-name": 1,
         "jsdoc/require-param-type": 1,
         "jsdoc/require-returns": 1,
+        "jsdoc/require-returns-check": 1,
         "jsdoc/require-returns-description": 1,
         "jsdoc/require-returns-type": 1,
         "jsdoc/valid-types": 1
@@ -259,5 +261,6 @@ Finally, the following rule pertains to inline disable directives:
 {"gitdown": "include", "file": "./rules/require-param.md"}
 {"gitdown": "include", "file": "./rules/require-returns-description.md"}
 {"gitdown": "include", "file": "./rules/require-returns-type.md"}
+{"gitdown": "include", "file": "./rules/require-returns-check.md"}
 {"gitdown": "include", "file": "./rules/require-returns.md"}
 {"gitdown": "include", "file": "./rules/valid-types.md"}

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

@@ -0,0 +1,10 @@
+### `require-returns-check`
+
+Checks if the return expression exists in function body and in the comment.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|`returns`|
+
+<!-- assertions requireReturnsCheck -->

src/index.js

@@ -14,6 +14,7 @@ import requireParam from './rules/requireParam';
 import requireParamDescription from './rules/requireParamDescription';
 import requireParamType from './rules/requireParamType';
 import requireReturns from './rules/requireReturns';
+import requireReturnsCheck from './rules/requireReturnsCheck';
 import requireReturnsDescription from './rules/requireReturnsDescription';
 import requireReturnsType from './rules/requireReturnsType';
 import validTypes from './rules/validTypes';
@@ -37,6 +38,7 @@ export default {
         'jsdoc/require-param-name': 'warn',
         'jsdoc/require-param-type': 'warn',
         'jsdoc/require-returns': 'warn',
+        'jsdoc/require-returns-check': 'warn',
         'jsdoc/require-returns-description': 'warn',
         'jsdoc/require-returns-type': 'warn',
         'jsdoc/valid-types': 'warn'
@@ -59,6 +61,7 @@ export default {
     'require-param-name': requireParamName,
     'require-param-type': requireParamType,
     'require-returns': requireReturns,
+    'require-returns-check': requireReturnsCheck,
     'require-returns-description': requireReturnsDescription,
     'require-returns-type': requireReturnsType,
     'valid-types': validTypes

src/rules/requireReturns.js

@@ -17,8 +17,4 @@ export default iterateJsdoc(({
   if (JSON.stringify(jsdocTags) === '[]' && sourcecode.indexOf('return') >= 1) {
     report('Missing JSDoc @' + targetTagName + ' declaration.');
   }
-
-  if (JSON.stringify(jsdocTags) !== '[]' && sourcecode.indexOf('return') < 1) {
-    report('Present JSDoc @' + targetTagName + ' declaration but not available return expression in function.');
-  }
 });

src/rules/requireReturnsCheck.js

@@ -0,0 +1,24 @@
+import _ from 'lodash';
+import iterateJsdoc from '../iterateJsdoc';
+
+export default iterateJsdoc(({
+  jsdoc,
+  report,
+  utils
+}) => {
+  const targetTagName = utils.getPreferredTagName('returns');
+
+  const jsdocTags = _.filter(jsdoc.tags, {
+    tag: targetTagName
+  });
+
+  const sourcecode = utils.getFunctionSourceCode();
+
+  const voidReturn = jsdocTags.findIndex((vundef) => {
+    return ['undefined', 'void'].indexOf(vundef.type) !== -1;
+  }) === -1;
+
+  if (JSON.stringify(jsdocTags) !== '[]' && voidReturn && sourcecode.indexOf('return') < 1) {
+    report('Present JSDoc @' + targetTagName + ' declaration but not available return expression in function.');
+  }
+});

test/rules/assertions/requireReturnsCheck.js

@@ -0,0 +1,87 @@
+export default {
+  invalid: [
+    {
+      code: `
+          /**
+           * @returns
+           */
+          function quux (foo) {
+
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Present JSDoc @returns declaration but not available return expression in function.'
+        }
+      ]
+    },
+    {
+      code: `
+          /**
+           * @return
+           */
+          function quux (foo) {
+
+          }
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Present JSDoc @return declaration but not available return expression in function.'
+        }
+      ],
+      settings: {
+        jsdoc: {
+          tagNamePreference: {
+            returns: 'return'
+          }
+        }
+      }
+    }
+  ],
+  valid: [
+    {
+      code: `
+          /**
+           * @returns Foo.
+           */
+          function quux () {
+
+            return foo;
+          }
+      `
+    },
+    {
+      code: `
+          /**
+           * @returns {void} Foo.
+           */
+          function quux () {
+
+            return foo;
+          }
+      `
+    },
+    {
+      code: `
+          /**
+           * @returns {undefined} Foo.
+           */
+          function quux () {
+
+            return foo;
+          }
+      `
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          function quux () {
+          }
+      `
+    }
+  ]
+};

test/rules/index.js

@@ -22,6 +22,7 @@ _.forEach([
   'require-param-name',
   'require-param-type',
   'require-returns',
+  'require-returns-check',
   'require-returns-description',
   'require-returns-type',
   'valid-types'