feat(require-returns-check): with settings.jsdoc.mode (typescript or gcc), allow yieldAsReturn option as "always" or "argument" to treat yield as return (fixes #271)

Author: brettz9

Diff for: .README/README.md

@@ -83,6 +83,12 @@ You can then selectively add to or override the recommended rules.
 
 ## Settings
 
+### Mode
+
+While TypeScript and the Google Closure Compiler (GCC) support some jsdoc tags,
+there are some differences. The `settings.jsdoc.mode` lets you choose the precise
+mode (`"typescript"`, `"gcc"`, or `"jsdoc"` (the default)).
+
 ### Allow `@private` to disable rules for that comment block
 
 - `settings.jsdoc.ignorePrivate` - Disables all rules for the comment block

Diff for: .README/rules/require-returns-check.md

@@ -4,6 +4,19 @@ Requires a return statement in function body if a `@returns` tag is specified in
 
 Will also report if multiple `@returns` tags are present.
 
+#### Options
+
+##### `yieldAsReturn`
+
+If the setting `settings.jsdoc.mode` is set to `typescript` or `gcc`, this option
+will allow `yield` statements to be treated as `@returns` for the purposes of this
+rule. (If the mode is instead `jsdoc`, then this option will have no effect, since
+the jsdoc approach is to instead use the `@yields` tag.)
+
+The allowable values are `"always"` which will treat any `yield` as a `return`,
+or `argument`, which will only treat a `yield` as a `return` when `yield` is
+followed by an argument.
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|

Diff for: README.md

@@ -12,6 +12,7 @@ JSDoc linting rules for ESLint.
     * [Installation](#eslint-plugin-jsdoc-installation)
     * [Configuration](#eslint-plugin-jsdoc-configuration)
     * [Settings](#eslint-plugin-jsdoc-settings)
+        * [Mode](#eslint-plugin-jsdoc-settings-mode)
         * [Allow `@private` to disable rules for that comment block](#eslint-plugin-jsdoc-settings-allow-private-to-disable-rules-for-that-comment-block)
         * [Alias Preference](#eslint-plugin-jsdoc-settings-alias-preference)
         * [`@override`/`@augments`/`@extends`/`@implements` Without Accompanying `@param`/`@description`/`@example`/`@returns`](#eslint-plugin-jsdoc-settings-override-augments-extends-implements-without-accompanying-param-description-example-returns)
@@ -122,6 +123,13 @@ You can then selectively add to or override the recommended rules.
 <a name="eslint-plugin-jsdoc-settings"></a>
 ## Settings
 
+<a name="eslint-plugin-jsdoc-settings-mode"></a>
+### Mode
+
+While TypeScript and the Google Closure Compiler (GCC) support some jsdoc tags,
+there are some differences. The `settings.jsdoc.mode` lets you choose the precise
+mode (`"typescript"`, `"gcc"`, or `"jsdoc"` (the default)).
+
 <a name="eslint-plugin-jsdoc-settings-allow-private-to-disable-rules-for-that-comment-block"></a>
 ### Allow <code>@private</code> to disable rules for that comment block
 
@@ -6324,6 +6332,21 @@ Requires a return statement in function body if a `@returns` tag is specified in
 
 Will also report if multiple `@returns` tags are present.
 
+<a name="eslint-plugin-jsdoc-rules-require-returns-check-options-12"></a>
+#### Options
+
+<a name="eslint-plugin-jsdoc-rules-require-returns-check-options-12-yieldasreturn"></a>
+##### <code>yieldAsReturn</code>
+
+If the setting `settings.jsdoc.mode` is set to `typescript` or `gcc`, this option
+will allow `yield` statements to be treated as `@returns` for the purposes of this
+rule. (If the mode is instead `jsdoc`, then this option will have no effect, since
+the jsdoc approach is to instead use the `@yields` tag.)
+
+The allowable values are `"always"` which will treat any `yield` as a `return`,
+or `argument`, which will only treat a `yield` as a `return` when `yield` is
+followed by an argument.
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
@@ -6394,6 +6417,59 @@ function quux () {
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"returns":false}}}
 // Message: Unexpected tag `@returns`
+
+/**
+ *
+ * @returns {boolean}
+ */
+function * quux () {
+}
+// Settings: {"jsdoc":{"mode":"typescript"}}
+// Options: [{"yieldAsReturn":"always"}]
+// Message: JSDoc @returns declaration present but return expression not available in function.
+
+/**
+ *
+ * @returns {boolean}
+ */
+function * quux () {
+}
+// Settings: {"jsdoc":{"mode":"typescript"}}
+// Options: [{"yieldAsReturn":"argument"}]
+// Message: JSDoc @returns declaration present but return expression not available in function.
+
+/**
+ *
+ * @returns {boolean}
+ */
+function * quux () {
+  yield;
+}
+// Settings: {"jsdoc":{"mode":"typescript"}}
+// Options: [{"yieldAsReturn":"argument"}]
+// Message: JSDoc @returns declaration present but return expression not available in function.
+
+/**
+ *
+ * @returns {boolean}
+ */
+function * quux () {
+  var a = 5, b = yield;
+}
+// Settings: {"jsdoc":{"mode":"typescript"}}
+// Options: [{"yieldAsReturn":"argument"}]
+// Message: JSDoc @returns declaration present but return expression not available in function.
+
+/**
+ *
+ * @returns {boolean}
+ */
+function * quux () {
+  yield true;
+}
+// Settings: {"jsdoc":{"mode":"jsdoc"}}
+// Options: [{"yieldAsReturn":"always"}]
+// Message: JSDoc @returns declaration present but return expression not available in function.
 ````
 
 The following patterns are not considered problems:
@@ -6650,6 +6726,46 @@ function quux () {
   }
   return;
 }
+
+/**
+ *
+ * @returns {boolean}
+ */
+function * quux () {
+  yield true;
+}
+// Settings: {"jsdoc":{"mode":"typescript"}}
+// Options: [{"yieldAsReturn":"always"}]
+
+/**
+ *
+ * @returns {boolean}
+ */
+function * quux () {
+  return true;
+}
+// Settings: {"jsdoc":{"mode":"typescript"}}
+// Options: [{"yieldAsReturn":"always"}]
+
+/**
+ *
+ * @returns {boolean}
+ */
+function * quux () {
+  yield true;
+}
+// Settings: {"jsdoc":{"mode":"typescript"}}
+// Options: [{"yieldAsReturn":"argument"}]
+
+/**
+ *
+ * @returns {boolean}
+ */
+function * quux () {
+  var a = 5, b = yield true;
+}
+// Settings: {"jsdoc":{"mode":"typescript"}}
+// Options: [{"yieldAsReturn":"argument"}]
 ````
 
 
@@ -6795,7 +6911,7 @@ Requires returns are documented.
 
 Will also report if multiple `@returns` tags are present.
 
-<a name="eslint-plugin-jsdoc-rules-require-returns-options-12"></a>
+<a name="eslint-plugin-jsdoc-rules-require-returns-options-13"></a>
 #### Options
 
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
@@ -7251,7 +7367,7 @@ Also impacts behaviors on namepath (or event)-defining and pointing tags:
    allow `#`, `.`, or `~` at the end (which is not allowed at the end of
    normal paths).
 
-<a name="eslint-plugin-jsdoc-rules-valid-types-options-13"></a>
+<a name="eslint-plugin-jsdoc-rules-valid-types-options-14"></a>
 #### Options
 
 - `allowEmptyNamepaths` (default: true) - Set to `false` to disallow

Diff for: src/iterateJsdoc.js

@@ -201,8 +201,11 @@ const getUtils = (
     return jsdocUtils.hasDefinedTypeReturnTag(tag);
   };
 
-  utils.hasReturnValue = (ignoreAsync = false) => {
-    return jsdocUtils.hasReturnValue(node, context, ignoreAsync);
+  utils.hasReturnValue = ({ignoreAsync = false, yieldAsReturn} = {}) => {
+    return jsdocUtils.hasReturnValue(node, context, {
+      ignoreAsync,
+      yieldAsReturn
+    });
   };
 
   utils.isAsync = () => {
@@ -319,6 +322,9 @@ const getSettings = (context) => {
   settings.implementsReplacesDocs = _.get(context, 'settings.jsdoc.implementsReplacesDocs');
   settings.augmentsExtendsReplacesDocs = _.get(context, 'settings.jsdoc.augmentsExtendsReplacesDocs');
 
+  // currently `require-returns-check` only, but to add to other rules
+  settings.mode = _.get(context, 'settings.jsdoc.mode');
+
   return settings;
 };