eslint-plugin-jsdoc 44.2.3 → 44.2.5

package/docs/rules/require-yields-check.md

@@ -1,326 +1,362 @@
-<a name="user-content-require-yields"></a>
-<a name="require-yields"></a>
-# <code>require-yields</code>
+<a name="user-content-require-yields-check"></a>
+<a name="require-yields-check"></a>
+# <code>require-yields-check</code>
 
-* [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)
+* [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)
 
 
-Requires that yields are documented.
+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).
 
-Will also report if multiple `@yields` tags are 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.
 
-See the `next`, `forceRequireNext`, and `nextWithGeneratorTag` options for an
-option to expect a non-standard `@next` tag.
+Will also report if multiple `@yields` tags are present.
 
-<a name="user-content-require-yields-options"></a>
-<a name="require-yields-options"></a>
+<a name="user-content-require-yields-check-options"></a>
+<a name="require-yields-check-options"></a>
 ## Options
 
-- `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>
+- `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>
 ## Context and settings
 
 |||
 |---|---|
-|Context|Generator functions (`FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled)|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|`yields`|
 |Aliases|`yield`|
 |Recommended|true|
-| Options  | `contexts`,  `exemptedBy`, `withGeneratorTag`, `nextWithGeneratorTag`, `forceRequireYields`, `next` |
-| Settings | `ignoreReplacesDocs`, `overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs` |
+|Options|`checkGeneratorsOnly`|
 
-<a name="user-content-require-yields-failing-examples"></a>
-<a name="require-yields-failing-examples"></a>
+<a name="user-content-require-yields-check-failing-examples"></a>
+<a name="require-yields-check-failing-examples"></a>
 ## Failing examples
 
 The following patterns are considered problems:
 
 ````js
 /**
- *
+ * @yields
  */
 function * quux (foo) {
 
-  yield foo;
 }
-// Message: Missing JSDoc @yields declaration.
+// Message: JSDoc @yields declaration present but yield expression not available in function.
 
 /**
  * @yields
  */
-function * quux (foo) {
+function quux (foo) {
 
-  const retVal = yield foo;
 }
-// "jsdoc/require-yields": ["error"|"warn", {"next":true}]
-// Message: Missing JSDoc @next declaration.
+// "jsdoc/require-yields-check": ["error"|"warn", {"checkGeneratorsOnly":true}]
+// Message: JSDoc @yields declaration present but yield expression not available in function.
 
 /**
- * @yields
+ * @next
  */
-function * quux (foo) {
+function quux (foo) {
 
-  const retVal = yield;
 }
-// "jsdoc/require-yields": ["error"|"warn", {"next":true}]
-// Message: Missing JSDoc @next declaration.
+// "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.
 
 /**
- * @yields {void}
+ * @next {SomeType}
  */
-function * quux () {
+function * quux (foo) {
+
 }
-// "jsdoc/require-yields": ["error"|"warn", {"forceRequireNext":true}]
-// Message: Missing JSDoc @next declaration.
+// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
+// Message: JSDoc @next declaration present but yield expression with return value not available in function.
 
 /**
- * @yields {void}
+ * @next {SomeType}
  */
-function * quux () {
+function * quux (foo) {
   yield;
 }
-// "jsdoc/require-yields": ["error"|"warn", {"forceRequireNext":true}]
-// Message: Missing JSDoc @next declaration.
+// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
+// Message: JSDoc @next declaration present but yield expression with return value not available in function.
 
 /**
- *
+ * @next {SomeType}
  */
 function * quux (foo) {
-
-  const a = yield foo;
+  yield 5;
 }
-// Message: Missing JSDoc @yields declaration.
+// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
+// Message: JSDoc @next declaration present but yield expression with return value not available in function.
 
 /**
- *
+ * @yield
  */
 function * quux (foo) {
-  yield foo;
+
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"yields":"yield"}}}
-// Message: Missing JSDoc @yield declaration.
+// Message: JSDoc @yield declaration present but yield expression not available in function.
 
 /**
- * @yields
+ * @yield-returns {Something}
  */
 function * quux (foo) {
-  const val = yield foo;
+  yield;
 }
 // Settings: {"jsdoc":{"tagNamePreference":{"next":"yield-returns"}}}
-// "jsdoc/require-yields": ["error"|"warn", {"next":true}]
-// Message: Missing JSDoc @yield-returns declaration.
+// "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.
 
 /**
  * @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": ["error"|"warn", {"next":true}]
+// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
 // Message: Unexpected tag `@next`
 
 /**
- *
+ * @yields {string}
  */
-function * quux() {
-  yield 5;
+function * f () {
+  function * g() {
+    yield 'foo'
+  }
 }
-// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
-// Message: Missing JSDoc @yields declaration.
+// Message: JSDoc @yields declaration present but yield expression not available in function.
 
 /**
- *
+ * @yields {Promise<void>}
  */
-function * quux() {
-  yield;
+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 () {
+  yield 5;
 }
-// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
-// Message: Missing JSDoc @yields declaration.
+// Message: JSDoc @yields declaration set with "never" but yield expression is present in function.
 
 /**
- *
+ * @next {never}
  */
-const quux = async function * () {
-  yield;
+function * quux (foo) {
+  const a = yield;
 }
-// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
-// Message: Missing JSDoc @yields declaration.
+// "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.
  */
-async function * quux () {
-  yield;
+function * quux () {
+
+  yield foo;
 }
-// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
-// Message: Missing JSDoc @yields declaration.
 
 /**
- *
+ * @yields {string} Foo.
  */
 function * quux () {
-  yield;
+
+  yield foo;
 }
-// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"forceRequireYields":true}]
-// Message: Missing JSDoc @yields declaration.
 
 /**
- * @function
- * @generator
+ * @yields {string} Foo.
  */
-// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"forceRequireYields":true}]
-// Message: Missing JSDoc @yields declaration.
+function * quux () {
+
+  yield foo;
+}
 
 /**
- * @callback
- * @generator
+ *
  */
-// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"forceRequireYields":true}]
-// Message: Missing JSDoc @yields declaration.
+function * quux () {
+}
 
 /**
- * @yields {undefined}
- * @yields {void}
+ * @yields {undefined} Foo.
  */
-function * quux (foo) {
+function * quux () {}
 
-  return foo;
-}
-// Message: Found more than one @yields declaration.
+/**
+ * @yields { void } Foo.
+ */
+function quux () {}
 
 /**
- * @yields
+ * @yields Foo.
+ * @abstract
  */
 function * quux () {
-
+  throw new Error('must be implemented by subclass!');
 }
-// Settings: {"jsdoc":{"tagNamePreference":{"yields":false}}}
-// Message: Unexpected tag `@yields`
 
 /**
- * @param foo
+ * @yields Foo.
+ * @virtual
  */
-function * quux (foo) {
-  yield 'bar';
+function * quux () {
+  throw new Error('must be implemented by subclass!');
 }
-// "jsdoc/require-yields": ["error"|"warn", {"exemptedBy":["notPresent"]}]
-// Message: Missing JSDoc @yields declaration.
 
 /**
- * @param {array} a
+ * @yields Foo.
+ * @constructor
  */
-async function * foo(a) {
-  return;
+function * quux () {
 }
-// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
-// Message: Missing JSDoc @yields declaration.
 
 /**
- * @param {array} a
+ * @interface
  */
-async function * foo(a) {
-  yield Promise.all(a);
+class Foo {
+  /**
+   * @yields {string}
+   */
+  * bar () {
+  }
 }
-// "jsdoc/require-yields": ["error"|"warn", {"forceRequireYields":true}]
-// Message: Missing JSDoc @yields declaration.
 
-class quux {
+/**
+ * @record
+ */
+class Foo {
   /**
-   *
+   * @yields {string}
    */
-  * quux () {
-    yield;
+  * bar () {
   }
 }
-// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"forceRequireYields":true}]
-// Message: Missing JSDoc @yields declaration.
+// Settings: {"jsdoc":{"mode":"closure"}}
 
 /**
- * @param {array} a
+ * @yields {undefined} Foo.
  */
-async function * foo(a) {
-  yield Promise.all(a);
+function * quux () {
 }
-// Message: Missing JSDoc @yields declaration.
 
 /**
- * @generator
+ * @yields {void} Foo.
  */
-// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"withGeneratorTag":true}]
-// Message: Missing JSDoc @yields declaration.
+function * quux () {
+}
 
 /**
- * @generator
- * @yields
+ * @yields {never} Foo.
+ */
+function * quux () {
+}
+
+/**
+ * @yields {void} Foo.
  */
-// "jsdoc/require-yields": ["error"|"warn", {"contexts":["any"],"nextWithGeneratorTag":true}]
-// Message: Missing JSDoc @next declaration.
+function * quux () {
+  yield undefined;
+}
+
+/**
+ * @yields {void} Foo.
+ */
+function * quux () {
+  yield;
+}
 
 /**
  *
  */
 function * quux () {
-  if (true) {
-    yield;
-  }
-  yield true;
+  yield undefined;
 }
-// Message: Missing JSDoc @yields declaration.
 
 /**
  *
  */
+function * quux () {
+  yield;
+}
+
+/**
+ * @yields {true}
+ */
 function * quux () {
   try {
     yield true;
@@ -328,10 +364,9 @@ function * quux () {
   }
   yield;
 }
-// Message: Missing JSDoc @yields declaration.
 
 /**
- *
+ * @yields {true}
  */
 function * quux () {
   try {
@@ -340,10 +375,9 @@ function * quux () {
   }
   yield;
 }
-// Message: Missing JSDoc @yields declaration.
 
 /**
- *
+ * @yields {true}
  */
 function * quux () {
   try {
@@ -352,10 +386,9 @@ function * quux () {
   }
   yield true;
 }
-// Message: Missing JSDoc @yields declaration.
 
 /**
- *
+ * @yields {true}
  */
 function * quux () {
   try {
@@ -365,10 +398,9 @@ function * quux () {
   }
   yield;
 }
-// Message: Missing JSDoc @yields declaration.
 
 /**
- *
+ * @yields {true}
  */
 function * quux () {
   switch (true) {
@@ -377,10 +409,9 @@ function * quux () {
   }
   yield;
 }
-// Message: Missing JSDoc @yields declaration.
 
 /**
- *
+ * @yields {true}
  */
 function * quux () {
   switch (true) {
@@ -389,10 +420,9 @@ function * quux () {
   }
   yield true;
 }
-// Message: Missing JSDoc @yields declaration.
 
 /**
- *
+ * @yields {true}
  */
 function * quux () {
   for (const i of abc) {
@@ -400,40 +430,36 @@ 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 {
@@ -441,10 +467,9 @@ function * quux () {
   }
   while(true)
 }
-// Message: Missing JSDoc @yields declaration.
 
 /**
- *
+ * @yields {true}
  */
 function * quux () {
   if (true) {
@@ -452,20 +477,18 @@ 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 = {};
@@ -473,10 +496,9 @@ function * quux () {
     yield true;
   }
 }
-// Message: Missing JSDoc @yields declaration.
 
 /**
- *
+ * @yields {true}
  */
 function * quux () {
   if (true) {
@@ -486,338 +508,37 @@ 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;
-}
-
-/**
- * @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;
-}
-
-/**
- * @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 foo;
 }
+// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
 
 /**
- * @yields
- * @next
+ * @next {SomeType}
  */
 function * quux (foo) {
-  let a = yield;
+  const a = yield;
 }
-// "jsdoc/require-yields": ["error"|"warn", {"next":true}]
+// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
 
 /**
- * @yields
- * @next
+ * @next {SomeType}
  */
 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;
+  const a = yield 5;
 }
-// "jsdoc/require-yields": ["error"|"warn", {"next":true}]
+// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
 
 /**
- *
+ * @next {never}
  */
 function * quux (foo) {
-  const a = function * bar () {
-    yield foo;
-  }
+
 }
+// "jsdoc/require-yields-check": ["error"|"warn", {"next":true}]
 ````