Add async generator documentation

[Josh-Cena]

Summary

Fix #1459
Fix #2248
Fix #2803

Continuation of #2861. Most credit goes to @DerekNonGeneric.

For now this is still a draft, only submitting because I suck at branch management and I risk accidentally deleting this branch if not published to remote while cleaning all local branches. TODOs:

• Port Document throw() & return() of iterators; correct description of generator methods #17431 here
• Documentation for async function* statement
• Documentation for @@asyncIterator
• Other normalization & editorial fixes

(First time trying the workflow of using gh pr checkout to checkout a fork's branch and then pushing to a different forked remote. Looks like it works?)

Motivation

Supporting details

Related issues

Metadata

• Adds a new document
• Rewrites (or significantly expands) a document
• Fixes a typo, bug, or other error

[github-actions]

Preview URLs

• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncFunction
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator/next
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator/return
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator/throw
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGeneratorFunction
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/Function
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator/next
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Global_Objects/GeneratorFunction
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Iteration_protocols
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Operators/async_function*
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Operators/async_function
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Operators/function*
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Operators/function
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Operators
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Statements/async_function*
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Statements/async_function
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Statements/function*
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Statements/function
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference/Statements
• https://pr17529.content.dev.mdn.mozit.cloud/en-US/docs/Web/JavaScript/Reference

Flaws

Note! 21 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/JavaScript/Reference
Title: JavaScript reference
on GitHub
Flaw count: 1

• macros:
  • wrong xref macro used (consider changing which macro you use)

---

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGeneratorFunction
Title: AsyncGeneratorFunction
on GitHub
Flaw count: 1

• broken_links:
  • Can't resolve /en-US/docs/Web/JavaScript/Guide/Iterators_and_generators

---

URL: /en-US/docs/Web/JavaScript/Reference/Operators/function*
Title: function* expression
on GitHub
Flaw count: 1

• macros:
  • /en-US/docs/Web/JavaScript/Reference/Functions_and_function_scope redirects to /en-US/docs/Web/JavaScript/Reference/Functions

External URLs

URL: /en-US/docs/Web/JavaScript/Reference
Title: JavaScript reference
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Statements
Title: Statements and declarations
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Statements/function*
Title: function*
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Statements/async_function*
Title: async function*
on GitHub

• https://nodejs.org/dist/latest-v18.x/docs/api/fs.html (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/JavaScript/Reference/Statements/async_function
Title: async function
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Statements/for-await...of
Title: for await...of
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Statements/function
Title: function declaration
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Iteration_protocols
Title: Iteration protocols
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator
Title: Symbol.asyncIterator
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGeneratorFunction
Title: AsyncGeneratorFunction
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/GeneratorFunction
Title: GeneratorFunction
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncFunction
Title: AsyncFunction
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator
Title: AsyncGenerator
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator/return
Title: AsyncGenerator.prototype.return()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator/next
Title: AsyncGenerator.prototype.next()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator/throw
Title: AsyncGenerator.prototype.throw()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/Function
Title: Function() constructor
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator
Title: Generator
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator/next
Title: Generator.prototype.next()
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Operators
Title: Expressions and operators
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Operators/function*
Title: function* expression
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Operators/async_function*
Title: async function* expression
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Operators/async_function
Title: async function expression
on GitHub

No new external URLs

---

URL: /en-US/docs/Web/JavaScript/Reference/Operators/function
Title: Function expression
on GitHub

No new external URLs

(this comment was updated 2022-07-16 10:49:08.770290)

[Josh-Cena]

A lot of the examples here are directly ported from their sync counterparts and appear overly contrived. Welcoming more examples since I can't think of any async work besides database connection, file system access, and web requests. (Maybe I should make examples with fetch?)

[DerekNonGeneric]

I would like to invite @lmammino to have a look as he recently released an iteration protocols workshop on the topic. Hopefully he would be able to spot any glaring transgressions wrt the protocols' documentation.

[teoli2003]

I have one nit. Re-request my review when this is ready to be merged.

[Josh-Cena]

I've slightly reworked the examples. I think async generators are not very useful without bringing some external APIs like fetch or fs.readFile, so I've changed my mind a bit and believe contrived examples are not that bad, as long as we illustrate how async generators can be used. How they are made can be in follow-up PRs if someone has better examples.

[ghost]

I've slightly reworked the examples. I think async generators are not very useful without bringing some external APIs like fetch or fs.readFile, so I've changed my mind a bit and believe contrived examples are not that bad, as long as we illustrate how async generators can be used. How they are made can be in follow-up PRs if someone has better examples.

I suppose a more contrived example that could be made would be converting Events with callbacks to an await for..of loop over a generator of Promise<Event>s? It still is an inherently asynchronous, and a note can be left about how this can give rise to API's such as Node.js's events.once.

[Josh-Cena]

I think the argument about tables vs. lists is well-made and deserves better attention. (It harms maintainability as well.) Shall we start a discussion?

[ghost]

The table wasn't completely removed(?)

[ghost]

Oh! iterable vs. iterator, sorry I didn't catch that; not sure if you want to remove that though, even though it is small.

[Josh-Cena]

I was thinking about it—this one seems trivial enough.

[teoli2003]

Let's land this \o/.

If more changes are needed, they can be in follow-ups. No need to hold this for perfection.

[lmammino]

Fantastic to see this landed! ❤️