eslint-plugin-jsdoc 44.2.3 → 44.2.4

package/docs/rules/require-yields.md

@@ -1,361 +1,325 @@
-<a name="user-content-require-yields-check"></a>
-<a name="require-yields-check"></a>
-# <code>require-yields-check</code>
+<a name="user-content-require-yields"></a>
+<a name="require-yields"></a>
+# <code>require-yields</code>
 
-* [Options](#user-content-require-yields-check-options)
-* [Context and settings](#user-content-require-yields-check-context-and-settings)
-* [Failing examples](#user-content-require-yields-check-failing-examples)
-* [Passing examples](#user-content-require-yields-check-passing-examples)
+* [Options](#user-content-require-yields-options)
+* [Context and settings](#user-content-require-yields-context-and-settings)
+* [Failing examples](#user-content-require-yields-failing-examples)
+* [Passing examples](#user-content-require-yields-passing-examples)
 
 
-Ensures that if a `@yields` is present that a `yield` (or `yield` with a
-value) is present in the function body (or that if a `@next` is present that
-there is a `yield` with a return value present).
-
-Please also note that JavaScript does allow generators not to have `yield`
-(e.g., with just a return or even no explicit return), but if you want to
-enforce that all generators (except wholly empty ones) have a `yield` in the
-function body, you can use the ESLint
-[`require-yield`](https://eslint.org/docs/rules/require-yield) rule. In
-conjunction with this, you can also use the `checkGeneratorsOnly` option
-as an optimization so that this rule won't need to do its own checking within
-function bodies.
+Requires that yields are documented.
 
 Will also report if multiple `@yields` tags are present.
 
-<a name="user-content-require-yields-check-options"></a>
-<a name="require-yields-check-options"></a>
+See the `next`, `forceRequireNext`, and `nextWithGeneratorTag` options for an
+option to expect a non-standard `@next` tag.
+
+<a name="user-content-require-yields-options"></a>
+<a name="require-yields-options"></a>
 ## Options
 
-- `checkGeneratorsOnly` - Avoids checking the function body and merely insists
-    that all generators have `@yields`. This can be an optimization with the
-    ESLint `require-yield` rule, as that rule already ensures a `yield` is
-    present in generators, albeit assuming the generator is not empty).
-    Defaults to `false`.
-- `next` - If `true`, this option will insist that any use of a (non-standard)
-    `@next` tag (in addition to any `@yields` tag) will be matched by a `yield`
-    which uses a return value in the body of the generator (e.g.,
-    `const rv = yield;` or `const rv = yield value;`). This (non-standard)
-    tag is intended to be used to indicate a type and/or description of
-    the value expected to be supplied by the user when supplied to the iterator
-    by its `next` method, as with `it.next(value)` (with the iterator being
-    the `Generator` iterator that is returned by the call to the generator
-    function). This option will report an error if the generator function body
-    merely has plain `yield;` or `yield value;` statements without returning
-    the values. Defaults to `false`.
-
-<a name="user-content-require-yields-check-context-and-settings"></a>
-<a name="require-yields-check-context-and-settings"></a>
+- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the
+    document block avoids the need for a `@yields`. Defaults to an array
+    with `inheritdoc`. If you set this array, it will overwrite the default,
+    so be sure to add back `inheritdoc` if you wish its presence to cause
+    exemption of the rule.
+- `forceRequireYields` - Set to `true` to always insist on
+    `@yields` documentation for generators even if there are only
+    expressionless `yield` statements in the function. May be desired to flag
+    that a project is aware of an `undefined`/`void` yield. Defaults to
+    `false`.
+- `contexts` - Set this to an array of strings representing the AST context
+    (or an object with `context` and `comment` properties) where you wish
+    the rule to be applied.
+    Overrides the default contexts (see below). Set to `"any"` if you want
+    the rule to apply to any jsdoc block throughout your files (as is necessary
+    for finding function blocks not attached to a function declaration or
+    expression, i.e., `@callback` or `@function` (or its aliases `@func` or
+    `@method`) (including those associated with an `@interface`). This
+    rule will only apply on non-default contexts when there is such a tag
+    present and the `forceRequireYields` option is set or if the
+    `withGeneratorTag` option is set with a present `@generator` tag
+    (since we are not checking against the actual `yield` values in these
+    cases).
+- `withGeneratorTag` - If a `@generator` tag is present on a block, require
+    `@yields`/`@yield`. Defaults to `true`. See `contexts` to `any` if you want
+    to catch `@generator` with `@callback` or such not attached to a function.
+- `next` - If `true`, this option will insist that any use of a `yield` return
+    value (e.g., `const rv = yield;` or `const rv = yield value;`) has a
+    (non-standard) `@next` tag (in addition to any `@yields` tag) so as to be
+    able to document the type expected to be supplied into the iterator
+    (the `Generator` iterator that is returned by the call to the generator
+    function) to the iterator (e.g., `it.next(value)`). The tag will not be
+    expected if the generator function body merely has plain `yield;` or
+    `yield value;` statements without returning the values. Defaults to
+    `false`.
+- `forceRequireNext` - Set to `true` to always insist on
+    `@next` documentation even if there are no `yield` statements in the
+    function or none return values. May be desired to flag that a project is
+    aware of the expected yield return being `undefined`. Defaults to `false`.
+- `nextWithGeneratorTag` - If a `@generator` tag is present on a block, require
+    (non-standard ) `@next` (see `next` option). This will require using `void`
+    or `undefined` in cases where generators do not use the `next()`-supplied
+    incoming `yield`-returned value. Defaults to `false`. See `contexts` to
+    `any` if you want to catch `@generator` with `@callback` or such not
+    attached to a function.
+
+<a name="user-content-require-yields-context-and-settings"></a>
+<a name="require-yields-context-and-settings"></a>
 ## Context and settings
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|Generator functions (`FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled)|
 |Tags|`yields`|
 |Aliases|`yield`|
 |Recommended|true|
-|Options|`checkGeneratorsOnly`|
+| Options  | `contexts`,  `exemptedBy`, `withGeneratorTag`, `nextWithGeneratorTag`, `forceRequireYields`, `next` |
+| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
 
-<a name="user-content-require-yields-check-failing-examples"></a>
-<a name="require-yields-check-failing-examples"></a>
+<a name="user-content-require-yields-failing-examples"></a>
+<a name="require-yields-failing-examples"></a>
 ## Failing examples
 
 The following patterns are considered problems:
 
 ````js
 /**
- * @yields
+ *
  */
 function * quux (foo) {
 
+  yield foo;
 }
-// Message: JSDoc @yields declaration present but yield expression not available in function.
+// Message: Missing JSDoc @yields declaration.
 
 /**
  * @yields
  */
-function quux (foo) {
+function * quux (foo) {
 
+  const retVal = yield foo;
 }
-// "jsdoc/require-yields-check": ["error"|"warn", {"checkGeneratorsOnly":true}]
-// Message: JSDoc @yields declaration present but yield expression not available in function.
+// "jsdoc/require-yields": ["error"|"warn", {"next":true}]
+// Message: Missing JSDoc @next declaration.
 
 /**
- * @next
+ * @yields
  */
-function quux (foo) {
+function * quux (foo) {
 
+  const retVal = yield;
 }
-// "jsdoc/require-yields-check": ["error"|"warn", {"checkGeneratorsOnly":true,"next":true}]
-// Message: JSDoc @next declaration present but yield expression with return value not available in function.
+// "jsdoc/require-yields": ["error"|"warn", {"next":true}]
+// Message: Missing JSDoc @next declaration.
 
 /**
- * @next {SomeType}
+ * @yields {void}
  */
-function * quux (foo) {
-
+function * quux () {
 }
-// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
-// Message: JSDoc @next declaration present but yield expression with return value not available in function.
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireNext":true}]
+// Message: Missing JSDoc @next declaration.
 
 /**
- * @next {SomeType}
+ * @yields {void}
  */
-function * quux (foo) {
+function * quux () {
   yield;
 }
-// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
-// Message: JSDoc @next declaration present but yield expression with return value not available in function.
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireNext":true}]
+// Message: Missing JSDoc @next declaration.
 
 /**
- * @next {SomeType}
+ *
  */
 function * quux (foo) {
-  yield 5;
+
+  const a = yield foo;
 }
-// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
-// Message: JSDoc @next declaration present but yield expression with return value not available in function.
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yield
+ *
  */
 function * quux (foo) {
-
+  yield foo;
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"yields":"yield"}}}
-// Message: JSDoc @yield declaration present but yield expression not available in function.
+// Message: Missing JSDoc @yield declaration.
 
 /**
- * @yield-returns {Something}
+ * @yields
  */
 function * quux (foo) {
-  yield;
+  const val = yield foo;
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"next":"yield-returns"}}}
-// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
-// Message: JSDoc @yield-returns declaration present but yield expression with return value not available in function.
-
-/**
- * @yields {undefined} Foo.
- * @yields {String} Foo.
- */
-function * quux () {
-
-  yield foo;
-}
-// Message: Found more than one @yields declaration.
-
-class Foo {
-  /**
-   * @yields {string}
-   */
-  * bar () {
-  }
-}
-// Message: JSDoc @yields declaration present but yield expression not available in function.
+// "jsdoc/require-yields": ["error"|"warn", {"next":true}]
+// Message: Missing JSDoc @yield-returns declaration.
 
 /**
  * @yields
- */
-function * quux () {
-
-}
-// Settings: {"jsdoc":{"tagNamePreference":{"yields":false}}}
-// Message: Unexpected tag `@yields`
-
-/**
  * @next
  */
 function * quux () {
-
+  const ret = yield 5;
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"next":false}}}
-// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
+// "jsdoc/require-yields": ["error"|"warn", {"next":true}]
 // Message: Unexpected tag `@next`
 
 /**
- * @yields {string}
- */
-function * f () {
-  function * g() {
-    yield 'foo'
-  }
-}
-// Message: JSDoc @yields declaration present but yield expression not available in function.
-
-/**
- * @yields {Promise<void>}
- */
-async function * quux() {}
-// Message: JSDoc @yields declaration present but yield expression not available in function.
-
-/**
- * @yields {Promise<void>}
- */
-const quux = async function * () {}
-// Message: JSDoc @yields declaration present but yield expression not available in function.
-
-/**
- * @yields {never} Foo.
+ *
  */
-function * quux () {
+function * quux() {
   yield 5;
 }
-// Message: JSDoc @yields declaration set with "never" but yield expression is present in function.
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @next {never}
- */
-function * quux (foo) {
-  const a = yield;
-}
-// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
-// Message: JSDoc @next declaration set with "never" but yield expression with return value is present in function.
-````
-
-
-
-<a name="user-content-require-yields-check-passing-examples"></a>
-<a name="require-yields-check-passing-examples"></a>
-## Passing examples
-
-The following patterns are not considered problems:
-
-````js
-/**
- * @yields Foo.
+ *
  */
-function * quux () {
-
-  yield foo;
+function * quux() {
+  yield;
 }
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {string} Foo.
+ *
  */
-function * quux () {
-
-  yield foo;
+const quux = async function * () {
+  yield;
 }
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {string} Foo.
+ *
  */
-function * quux () {
-
-  yield foo;
+async function * quux () {
+  yield;
 }
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
+// Message: Missing JSDoc @yields declaration.
 
 /**
  *
  */
 function * quux () {
+  yield;
 }
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"forceRequireYields":true}]
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {undefined} Foo.
+ * @function
+ * @generator
  */
-function * quux () {}
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"forceRequireYields":true}]
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields { void } Foo.
+ * @callback
+ * @generator
  */
-function quux () {}
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"forceRequireYields":true}]
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields Foo.
- * @abstract
+ * @yields {undefined}
+ * @yields {void}
  */
-function * quux () {
-  throw new Error('must be implemented by subclass!');
-}
+function * quux (foo) {
 
-/**
- * @yields Foo.
- * @virtual
- */
-function * quux () {
-  throw new Error('must be implemented by subclass!');
+  return foo;
 }
+// Message: Found more than one @yields declaration.
 
 /**
- * @yields Foo.
- * @constructor
+ * @yields
  */
 function * quux () {
-}
 
-/**
- * @interface
- */
-class Foo {
-  /**
-   * @yields {string}
-   */
-  * bar () {
-  }
 }
+// Settings: {"jsdoc":{"tagNamePreference":{"yields":false}}}
+// Message: Unexpected tag `@yields`
 
 /**
- * @record
+ * @param foo
  */
-class Foo {
-  /**
-   * @yields {string}
-   */
-  * bar () {
-  }
+function * quux (foo) {
+  yield 'bar';
 }
-// Settings: {"jsdoc":{"mode":"closure"}}
+// "jsdoc/require-yields": ["error"|"warn", {"exemptedBy":["notPresent"]}]
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {undefined} Foo.
+ * @param {array} a
  */
-function * quux () {
+async function * foo(a) {
+  return;
 }
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {void} Foo.
+ * @param {array} a
  */
-function * quux () {
+async function * foo(a) {
+  yield Promise.all(a);
 }
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
+// Message: Missing JSDoc @yields declaration.
 
-/**
- * @yields {never} Foo.
- */
-function * quux () {
+class quux {
+  /**
+   *
+   */
+  * quux () {
+    yield;
+  }
 }
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"forceRequireYields":true}]
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {void} Foo.
+ * @param {array} a
  */
-function * quux () {
-  yield undefined;
+async function * foo(a) {
+  yield Promise.all(a);
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {void} Foo.
+ * @generator
  */
-function * quux () {
-  yield;
-}
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"withGeneratorTag":true}]
+// Message: Missing JSDoc @yields declaration.
 
 /**
- *
+ * @generator
+ * @yields
  */
-function * quux () {
-  yield undefined;
-}
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"nextWithGeneratorTag":true}]
+// Message: Missing JSDoc @next declaration.
 
 /**
  *
  */
 function * quux () {
-  yield;
+  if (true) {
+    yield;
+  }
+  yield true;
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {true}
+ *
  */
 function * quux () {
   try {
@@ -364,9 +328,10 @@ function * quux () {
   }
   yield;
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {true}
+ *
  */
 function * quux () {
   try {
@@ -375,9 +340,10 @@ function * quux () {
   }
   yield;
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {true}
+ *
  */
 function * quux () {
   try {
@@ -386,9 +352,10 @@ function * quux () {
   }
   yield true;
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {true}
+ *
  */
 function * quux () {
   try {
@@ -398,9 +365,10 @@ function * quux () {
   }
   yield;
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {true}
+ *
  */
 function * quux () {
   switch (true) {
@@ -409,9 +377,10 @@ function * quux () {
   }
   yield;
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {true}
+ *
  */
 function * quux () {
   switch (true) {
@@ -420,9 +389,10 @@ function * quux () {
   }
   yield true;
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {true}
+ *
  */
 function * quux () {
   for (const i of abc) {
@@ -430,36 +400,40 @@ function * quux () {
   }
   yield;
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {true}
+ *
  */
 function * quux () {
   for (const a in b) {
     yield true;
   }
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {true}
+ *
  */
 function * quux () {
   for (let i=0; i<n; i+=1) {
     yield true;
   }
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {true}
+ *
  */
 function * quux () {
   while(true) {
     yield true
   }
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {true}
+ *
  */
 function * quux () {
   do {
@@ -467,9 +441,10 @@ function * quux () {
   }
   while(true)
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {true}
+ *
  */
 function * quux () {
   if (true) {
@@ -477,18 +452,20 @@ function * quux () {
   }
   yield true;
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {true}
+ *
  */
 function * quux () {
   if (true) {
     yield true;
   }
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {true}
+ *
  */
 function * quux () {
   var a = {};
@@ -496,9 +473,10 @@ function * quux () {
     yield true;
   }
 }
+// Message: Missing JSDoc @yields declaration.
 
 /**
- * @yields {true}
+ *
  */
 function * quux () {
   if (true) {
@@ -508,37 +486,338 @@ function * quux () {
   }
   yield;
 }
+// Message: Missing JSDoc @yields declaration.
+````
+
+
+
+<a name="user-content-require-yields-passing-examples"></a>
+<a name="require-yields-passing-examples"></a>
+## Passing examples
+
+The following patterns are not considered problems:
+
+````js
+/**
+ * @yields Foo.
+ */
+function * quux () {
+
+  yield foo;
+}
 
 /**
- * @next {void}
+ * @yields Foo.
+ */
+function * quux () {
+
+  yield foo;
+}
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"]}]
+
+/**
+ *
+ */
+function * quux () {
+}
+
+/**
+ *
+ */
+function * quux () {
+  yield;
+}
+
+/**
+ *
+ */
+function quux (bar) {
+  bar.doSomething(function * (baz) {
+    yield baz.corge();
+  })
+}
+
+/**
+ * @yields {Array}
+ */
+function * quux (bar) {
+  yield bar.doSomething(function * (baz) {
+    yield baz.corge();
+  })
+}
+
+/**
+ * @inheritdoc
  */
 function * quux (foo) {
+}
+
+/**
+ * @override
+ */
+function * quux (foo) {
+}
+
+/**
+ * @constructor
+ */
+function * quux (foo) {
+}
+
+/**
+ * @implements
+ */
+function * quux (foo) {
+  yield;
+}
+
+/**
+ * @override
+ */
+function * quux (foo) {
+
+  yield foo;
+}
+
+/**
+ * @class
+ */
+function * quux (foo) {
+  yield foo;
+}
+
+/**
+ * @constructor
+ */
+function * quux (foo) {
+}
+
+/**
+ * @yields {object}
+ */
+function * quux () {
+
+  yield {a: foo};
+}
+
+/**
+ * @yields {void}
+ */
+function * quux () {
+}
+
+/**
+ * @yields {undefined}
+ */
+function * quux () {
+}
+
+/**
+ *
+ */
+function * quux () {
+}
+
+/**
+ * @yields {void}
+ */
+function quux () {
+}
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
+
+/**
+ * @yields {void}
+ * @next {void}
+ */
+function * quux () {
+}
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireNext":true}]
+
+/**
+ * @yields {void}
+ */
+function * quux () {
+  yield undefined;
+}
+
+/**
+ * @yields {void}
+ */
+function * quux () {
+  yield undefined;
+}
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
+
+/**
+ * @yields {void}
+ */
+function * quux () {
+  yield;
+}
+
+/**
+ * @yields {void}
+ */
+function * quux () {
+}
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
+
+/**
+ * @yields {void}
+ */
+function * quux () {
+  yield;
+}
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
 
+/** @type {SpecialIterator} */
+function * quux () {
+  yield 5;
 }
-// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
 
 /**
- * @next {SomeType}
+ * @yields {Something}
+ */
+async function * quux () {
+}
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
+
+/**
+ *
+ */
+async function * quux () {}
+
+/**
+ *
+ */
+const quux = async function * () {}
+
+/**
+ * @type {MyCallback}
+ */
+function * quux () {
+  yield;
+}
+// "jsdoc/require-yields": ["error"|"warn", {"exemptedBy":["type"]}]
+
+/**
+ * @param {array} a
+ */
+async function * foo (a) {
+  yield;
+}
+
+/**
+ *
+ */
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"]}]
+
+/**
+ * @function
+ */
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"]}]
+
+/**
+ * @function
+ */
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
+
+/**
+ * @callback
+ */
+// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
+
+/**
+ * @generator
+ */
+// "jsdoc/require-yields": ["error"|"warn", {"withGeneratorTag":true}]
+
+/**
+ * @generator
+ */
+// "jsdoc/require-yields": ["error"|"warn", {"nextWithGeneratorTag":true}]
+
+/**
+ * @generator
+ * @yields
+ */
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"withGeneratorTag":true}]
+
+/**
+ * @generator
+ * @yields
+ * @next
+ */
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"nextWithGeneratorTag":true}]
+
+/**
+ * @generator
+ */
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"withGeneratorTag":false}]
+
+/**
+ * @generator
+ * @yields
+ */
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"nextWithGeneratorTag":false}]
+
+/**
+ * @yields
  */
 function * quux (foo) {
-  const a = yield;
+
+  const a = yield foo;
 }
-// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
 
 /**
- * @next {SomeType}
+ * @yields
+ * @next
  */
 function * quux (foo) {
-  const a = yield 5;
+  let a = yield;
 }
-// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
+// "jsdoc/require-yields": ["error"|"warn", {"next":true}]
 
 /**
- * @next {never}
+ * @yields
+ * @next
  */
 function * quux (foo) {
+  const a = yield foo;
+}
+// "jsdoc/require-yields": ["error"|"warn", {"next":true}]
 
+/**
+ *
+ */
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"nextWithGeneratorTag":true}]
+
+/**
+ *
+ */
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"next":true}]
+
+/**
+ *
+ */
+function quux () {}
+// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"next":true}]
+
+/**
+ * @yields {void}
+ */
+function * quux () {
+  yield;
+}
+// "jsdoc/require-yields": ["error"|"warn", {"next":true}]
+
+/**
+ *
+ */
+function * quux (foo) {
+  const a = function * bar () {
+    yield foo;
+  }
 }
-// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
 ````