typescript-eslint · kirkwaiblinger · Aug 30, 2024 · Aug 14, 2024 · Aug 15, 2024 · Aug 16, 2024
diff --git a/packages/eslint-plugin/docs/rules/require-await.mdx b/packages/eslint-plugin/docs/rules/require-await.mdx
@@ -12,14 +12,43 @@ import TabItem from '@theme/TabItem';
 This rule extends the base [`eslint/require-await`](https://eslint.org/docs/rules/require-await) rule.
 It uses type information to allow promise-returning functions to be marked as `async` without containing an `await` expression.
 
+:::note
+`yield` expressions in [async generator functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function*) behave differently from sync generator functions (they unwrap promises), so the base rule never checks async generator functions. On the other hand, our rule uses type information and can detect async generator functions that both never use `await` and always yield non-promise values.
+:::
+
 ## Examples
 
-Examples of **correct** code for this rule:
+<Tabs>
+<TabItem value="❌ Incorrect">
+
+```ts
+async function returnNumber() {
+  return 1;
+}
+
+async function* asyncGenerator() {
+  yield 1;
+}
+
+const num = returnNumber();
+const callAsyncGenerator = () => asyncGenerator();
+```
+
+</TabItem>
+<TabItem value="✅ Correct">
 
 ```ts
-async function returnsPromise1() {
-  return Promise.resolve(1);
+function returnNumber() {
+  return 1;
 }
 
-const returnsPromise2 = () => returnsPromise1();
+function* syncGenerator() {
+  yield 1;
+}
+
+const num = returnNumber();
+const callSyncGenerator = () => syncGenerator();
 ```
+
+</TabItem>
+</Tabs>
diff --git a/packages/eslint-plugin/tests/docs-eslint-output-snapshots/require-await.shot b/packages/eslint-plugin/tests/docs-eslint-output-snapshots/require-await.shot