1483152 - Document async iterators and generators

Status: RESOLVED INCOMPLETE

(Developer Documentation Graveyard :: JavaScript, enhancement, P2)

Description

[Florian Scholz (Open Web Docs)]

Documentation for https://tc39.github.io/proposal-async-iteration/ 
(this shipped in Firefox 57, see bug 1352312)

## Iteration protocol reference page:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols needs to talk about the async iteration protocol.


## Symbol.asyncIterator
Docs could probably be derived from Symbol.iterator https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator
It's already listed on the Symbol page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#Well-known_symbols
New page to be created here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator
Compat data update here: https://github.com/mdn/browser-compat-data/blob/master/javascript/builtins/Symbol.json#L58
New interactive example here: https://github.com/mdn/interactive-examples/tree/master/live-examples/js-examples/symbol


## for-await-of
Needs to be listed here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements#Iterations
New reference page here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await-of
New compat data entry here: https://github.com/mdn/browser-compat-data/blob/master/javascript/statements.json
New interactive example here: https://github.com/mdn/interactive-examples/tree/master/live-examples/js-examples/statement


## Async generators
We have https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*, maybe it would be worth doing an extra reference page about async function* ? Then you would create e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function* maybe. Also add compat data and interactive example again, like for the other two above.


## APIs that use async iterators / generators
I don't know all the APIs that use async iteration, but it seems like Streams are async iterables, so it might be interesting to look into our streams docs and update them if necessary https://developer.mozilla.org/en-US/docs/Web/API/Streams_API


## Guide page updates
We have https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_generators
Unfortunately we have no dedicated guide page yet on async JS programming. We want to create that at some point, though. See https://bugzilla.mozilla.org/show_bug.cgi?id=1305261 
More brainstorming on that here: https://docs.google.com/document/d/1ko8Xt5JaFVuXjEOHSyhw8MaxKPTbKiX6Qc7EXtczKUA/edit?ts=5b55b98b#heading=h.5tv0p4d6vqmu 


## Misc
Joe Medley contributed this: https://github.com/mdn/interactive-examples/pull/1036, check if it is integrated nicely.

Comment 1

[Chris Mills [:cmills]]

Closing; this is now being tracked at https://github.com/mdn/sprints/issues/1009