Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document “AsyncGenerator” & “AsyncGeneratorFunction” #2861

Closed
wants to merge 23 commits into from
Closed

Document “AsyncGenerator” & “AsyncGeneratorFunction” #2861

wants to merge 23 commits into from

Conversation

DerekNonGeneric
Copy link
Contributor

Adds pages for the AsyncGenerator and AsyncGeneratorFunction
standard built-in global objects that had been missing from the
“Control abstraction objects” section.

Fixes: #2803

/cc @sideshowbarker @Ryuno-Ki @wbamberg

Adds pages for the `AsyncGenerator` and `AsyncGeneratorFunction`
standard built-in global objects that had been missing from the
“Control abstraction objects” section.

Fixes: #2803
@DerekNonGeneric DerekNonGeneric requested a review from a team as a code owner March 4, 2021 20:00
@DerekNonGeneric DerekNonGeneric requested review from Rumyra and removed request for a team March 4, 2021 20:00
Copy link
Collaborator

@Ryuno-Ki Ryuno-Ki left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm assigned the SVG team, so feel free to ignore comments you deem irrelevant (but it might be that others will bring them up again).
I focussed mainly on editorial bits here.
Not checked out and run locally.

@DerekNonGeneric
Copy link
Contributor Author

Thanks for all the help so far @Ryuno-Ki — it should be in much better shape now!

Looking forward to seeing what the others think once they have a chance to take a look.

@Rumyra Rumyra self-assigned this Mar 8, 2021
@Rumyra
Copy link
Collaborator

Rumyra commented Mar 8, 2021

Currently having a look at this - it looks great thank you @DerekNonGeneric

Going to be a bit of time as I think BCD and member pages need to be looked at... will keep it updated in this conversation 👍

Copy link
Collaborator

@Ryuno-Ki Ryuno-Ki left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Look, a pending review (but only a small nitpick)

@Rumyra
Copy link
Collaborator

Rumyra commented Mar 9, 2021

I'm pushing updates to this branch now - with any luck it'll work 😬 Once I've figured out the correct remotes...

Awesome - looks like that worked - here are some things I've done:

  • General tidy up, additional macros etc...
  • Tag & see also review (some links removed as they appear in the sidebar)
  • Modified code examples to be more explicit/work without top level await

Let me know what you think @Ryuno-Ki and @DerekNonGeneric

The can of worms that has been opened because this needs thorough documenting are as follows (for my ref more than anything):

Complete list:

Which would tidy up most of the dead links. I'm inclined to merge this and create a new issue/issues for these however.

@DerekNonGeneric
Copy link
Contributor Author

Thanks for the tidying up @Rumyra — it looks great! I like that you added an example that uses for await. 👍

I'm inclined to merge this and create a new issue/issues for these however.

If it would be easier for you to keep track of the whole can of worms in a single PR (i.e., to ensure no content is duplicated), we can handle those in this PR if you would prefer. Feel free to continue work on this branch. Arguably we should at least add next(), return(), throw() pages in this PR to properly handle these two constructors. Up to you!

Copy link
Collaborator

@Rumyra Rumyra left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @DerekNonGeneric ☺️

@Rumyra
Copy link
Collaborator

Rumyra commented Mar 12, 2021

Thanks for the tidying up @Rumyra — it looks great! I like that you added an example that uses for await. 👍

I'm inclined to merge this and create a new issue/issues for these however.

If it would be easier for you to keep track of the whole can of worms in a single PR (i.e., to ensure no content is duplicated), we can handle those in this PR if you would prefer. Feel free to continue work on this branch. Arguably we should at least add next(), return(), throw() pages in this PR to properly handle these two constructors. Up to you!

Yes agreed - adding at least the methods to this PR would make it a nice rounded piece of work. We can do as previous and use the generator methods as a template

Also temporarily converting to draft so it doesn't get merged just yet

@Rumyra Rumyra marked this pull request as draft March 12, 2021 16:48
@DerekNonGeneric
Copy link
Contributor Author

DerekNonGeneric commented Mar 13, 2021

We can do as previous and use the generator methods as a template

I got that taken care of, which brought to light that the variable names in one of the examples could use improvement.


I think this is all we need to get this merged now:

  • a review of these new method pages
  • getting that browser compat data PR merged

@sideshowbarker
Copy link
Collaborator

@Rumyra Do you remember what this PR is waiting on? Glancing through the comments, it’s not clear to me at least…

@Rumyra
Copy link
Collaborator

Rumyra commented May 26, 2021

@sideshowbarker me :) The statement page still needs addressing - I'm just getting back to it now I'm back.

Here's a more clear checklist:

  • Statement page
  • Check interactive demos have been merged
  • Update probably conflicts from bcd/frontmatter amends (these pages were made before those changes were)

@github-actions
Copy link
Contributor

github-actions bot commented Jul 14, 2021

Preview URLs

Flaws

Note! 1 document with no flaws that don't need to be listed. 🎉

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

  • macros:
    • /en-US/docs/Web/JavaScript/Reference/Statements/async_function* does not exist
    • /en-US/docs/Web/JavaScript/Reference/Statements/for_each...in does not exist

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

  • macros:
    • /en-US/docs/Web/JavaScript/Reference/Statements/async_function* does not exist
  • bad_bcd_links:
    • no explanation!

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

  • macros:
    • /en-US/docs/Web/JavaScript/Reference/Statements/async_function* does not exist
    • /en-US/docs/Web/JavaScript/Reference/Statements/async_function* does not exist
    • /en-US/docs/Web/JavaScript/Reference/Functions_and_function_scope redirects to /en-US/docs/Web/JavaScript/Reference/Functions

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

  • macros:
    • /en-US/docs/Web/JavaScript/Reference/Statements/async_function* does not exist
    • /en-US/docs/Web/JavaScript/Reference/Statements/async_function* does not exist
    • /en-US/docs/Web/JavaScript/Reference/Statements/async_function* does not exist
    • /en-US/docs/Web/JavaScript/Reference/Statements/async_generator_function* does not exist
    • /en-US/docs/Web/JavaScript/Reference/Statements/async_function* does not exist
    • and 1 more flaws omitted
  • broken_links:
    • Can't resolve https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_generators

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

  • macros:
    • /en-US/docs/Web/JavaScript/Reference/Statements/async_function* does not exist
    • /en-US/docs/Web/JavaScript/Reference/Statements/async_function* does not exist
    • /en-US/docs/Web/JavaScript/Reference/Statements/async_function* does not exist
  • broken_links:
    • Anchor not lowercase
    • Anchor not lowercase
    • Can't resolve /en-US/docs/Web/JavaScript/Guide/The_Iterator_protocol

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

  • macros:
    • /en-US/docs/Web/JavaScript/Reference/Statements/async_function* does not exist

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

  • macros:
    • /en-US/docs/Web/JavaScript/Reference/Statements/async_function* does not exist
  • bad_pre_tags:
    • <pre><code>CODE can be just <pre>CODE

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

  • macros:
    • /en-US/docs/Web/JavaScript/Reference/Statements/async_function* does not exist

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/Operators
Title: Expressions and operators
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/Global_Objects/AsyncGeneratorFunction
Title: AsyncGeneratorFunction
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/throw
Title: AsyncGenerator.prototype.throw()
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

(this comment was updated 2021-07-14 16:08:45.690613)

@Rumyra
Copy link
Collaborator

Rumyra commented Jul 14, 2021

Soz I merged main into the latest commit and it's added a previous pr I made- I'll untangle after lunch 👍

This reverts commit c331788.
@Rumyra
Copy link
Collaborator

Rumyra commented Jul 14, 2021

OK I think this is all ready to go - albeit being converted to markdown. Note I have removed the statement page as it's going to take a bit of work and was blocking this PR from going through. I will open an issue for it in https://github.com/mdn/content/projects/11 once we've got this going.

  • I've merged main so hopefully we'll be conflict free 🤞
  • Tidied up frontmatter and included new bcd & spec macros
  • Interactive example has been tidied up here Async generator examples interactive-examples#1784 (this needs to be merged before this pr so I'll keep it as draft for now)

This could do all do with a good review @wbamberg @Elchi3 @sideshowbarker 🙏

@wbamberg
Copy link
Collaborator

About Markdown: it looks like there are 6 new files here:

files/en-us/web/javascript/reference/global_objects/asyncgenerator/index.html
files/en-us/web/javascript/reference/global_objects/asyncgenerator/next/index.html
files/en-us/web/javascript/reference/global_objects/asyncgenerator/return/index.html
files/en-us/web/javascript/reference/global_objects/asyncgenerator/throw/index.html
files/en-us/web/javascript/reference/global_objects/asyncgeneratorfunction/index.html
files/en-us/web/javascript/reference/operators/async_function_star_/index.html

...and updates to 3 existing ones:

files/en-us/web/javascript/reference/index.html
files/en-us/web/javascript/reference/operators/index.html
files/en-us/web/javascript/reference/statements/index.html

For the new files, I reckon it makes sense to convert to Markdown for this PR and land them they way, whether or not the rest of the JS docs are converted at that point. I'll try converting them and see what breaks.

For the existing files:

  • if we can land this before the rest of the JS docs, we could keep them as HTML in this PR and they will get converted in the Markdown PR
  • otherwise we could remove them from this PR entirely and file a follow-up for them, then this PR doesn't have to worry about Markdown timing at all

Copy link
Collaborator

@wbamberg wbamberg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had quite a few comments, but some of them might be me not understanding this very well.

There seems to be some systematic problem with a jsxref reference - I noted most of them but probably missed some, so it's worth checking them all.

<dt>{{jsxref("AsyncGenerator.prototype.return()")}}</dt>
<dd>Returns a {{jsxref("Promise")}} which will be resolved with the given value yielded by the {{jsxref("Operators/yield", "yield")}} expression and finishes the generator.</dd>
<dt>{{jsxref("AsyncGenerator.prototype.throw()")}}</dt>
<dd>Returns a {{jsxref("Promise")}} that is rejected with an exception thrown from (or uncaught from) within the async generator function and finishes the generator unless the exception is caught within that generator.</dd>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a long and complicated sentence and could do with splitting into 2, probably at the "function and finishes" juncture. It's also not very clear how to parse "(or uncaught from)" or how that relates to "unless the exception is caught within that generator".

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Talking about next and finishes make me think, whether a state chart might be helpful for comprehension.


<p>{{jsxref("Statements/async_function*", "async generator function")}} objects created with the <code>AsyncGeneratorFunction</code> constructor are parsed when the function is created. This is less efficient than declaring a generator function with an {{jsxref("Statements/async_function*", "async function* expression")}} and calling it within your code, because such functions are parsed with the rest of the code.</p>

<p>All arguments passed to the function are treated as the names of the identifiers of the parameters in the function to be created, in the order in which they are passed.</p>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Except for the final argument?


<div class="notecard note">
<h3>Note:</h3>
<p>{{jsxref("Statements/async_generator_function*", "async generator functions")}} created with the <code>AsyncGeneratorFunction</code> constructor do not create closures to their creation contexts; they are always created in the global scope.</p>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again "async generator functions" should be "Async generator functions" if it's not an identifier.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does global scope refers to here (in context of an ES module, for example. Would other modules see it, as in, it were defined on window as property)?


<h2 id="Syntax">Syntax</h2>

<pre class="brush: js">async function* [<var>name</var>]([<var>param1</var>[, <var>param2[</var>, ..., <var>paramN</var>]]]) {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I understand it we are not using this form of syntax any more. Instead we are using separate lines for the variations (cf https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/forEach#syntax).


<h2 id="Description">Description</h2>

<p>An <code>async function*</code> expression is very similar to and has almost the same syntax as a {{jsxref('Statements/async_function*', 'async function* statement', "", 1)}}. The main difference between an <code>async function*</code> expression and an <code>async function*</code> statement is the <em>function name</em>, which can be omitted in <code>async function*</code> expressions to create <em>anonymous</em> asynchronous generator functions. See also the chapter about {{jsxref("Functions", "functions")}} for more information.</p>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, since "functions" is not an identifier this should be {{jsxref("Functions", "functions", "", "1")}}

@wbamberg
Copy link
Collaborator

I've tried converting this to Markdown and found a couple of things worth changing, but it might be simpler to apply them after content reviews are done.

Copy link
Collaborator

@Ryuno-Ki Ryuno-Ki left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I totally not got a notification for #2861 (comment) (but got sent to commits instead which I shrugged away).

I looked at the documentation with an engineer's point of view. There are some inconsistencies which you might want to pick up or leave them as is. Your call :-)

<dt>{{jsxref("AsyncGenerator.prototype.return()")}}</dt>
<dd>Returns a {{jsxref("Promise")}} which will be resolved with the given value yielded by the {{jsxref("Operators/yield", "yield")}} expression and finishes the generator.</dd>
<dt>{{jsxref("AsyncGenerator.prototype.throw()")}}</dt>
<dd>Returns a {{jsxref("Promise")}} that is rejected with an exception thrown from (or uncaught from) within the async generator function and finishes the generator unless the exception is caught within that generator.</dd>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Talking about next and finishes make me think, whether a state chart might be helpful for comprehension.

<dl>
<dt><code><var>name</var></code> {{optional_inline}}</dt>
<dd>The function name. Can be omitted, in which case the function is <em>anonymous</em>. The name is only local to the function body.</dd>
<dt><code><var>paramN</var></code> {{optional_inline}}</dt>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In another file, you wrapped N in an em element.

<dt><code><var>name</var></code> {{optional_inline}}</dt>
<dd>The function name. Can be omitted, in which case the function is <em>anonymous</em>. The name is only local to the function body.</dd>
<dt><code><var>paramN</var></code> {{optional_inline}}</dt>
<dd>The name of an argument to be passed to the function. A function can have up to 255 arguments.</dd>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why 255 (= 256-1 = 2^8-1)?
What happens if I exceed that number?


<h3 id="Using_function*">Using async function*</h3>

<p>The following example defines an unnamed asynchronous generator function and assigns it to <code>x</code>. The function yields the square of its argument:</p>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't „unnamed” imply „asynchronous”?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

x is a bad variable name. square might be better.
(I don't want to teach code newbies bad practices, so no offense).

yield await Promise.resolve(y * y)
}

x(6).next().then(res => console.log(res.value)); // logs 36
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're using another comment style here as elsewhere.

@Ryuno-Ki
Copy link
Collaborator

I can see conflicting files here.

@Rumyra
Copy link
Collaborator

Rumyra commented Jul 31, 2021

Thanks! I'm working my way through all these comments 👍

I can see conflicting files here.

There should be - things have changed, that'll be the last thing I look at 👍

@teoli2003 teoli2003 added the Content:JS JavaScript docs label Sep 13, 2021
@sideshowbarker
Copy link
Collaborator

I’m not sure what this PR is waiting on currently, but it would be nice if we could get any remaining issues with it resolved and get it merged. In https://twitter.com/jcubic/status/1438938271761960968 someone who may be a potential contributor commented, “it has a lot of Open PR, the last open (on the last page) it's from March” (with an implication being that having PRs around that have been open for ~6 months might scare off some other potential contributors).

@wbamberg
Copy link
Collaborator

It looks like some review comments are not addressed yet, and after review it all needs to be converted to Markdown.

@DerekNonGeneric
Copy link
Contributor Author

@wbamberg, I was under the impression that @Rumyra was going to wrap things up here, but if she doesn't have the bandwidth to get it over the finish line at the moment, I am happy to do so. I know there were a lot of other tasks associated w/ getting this PR ready to land, so I will see if I can coordinate via Matrix in the next couple days to see what can be done on my end.

@Rumyra
Copy link
Collaborator

Rumyra commented Sep 20, 2021

I have a working branch for this pr addressing the reviews. Once that's complete I intend to convert to markdown. So I'm closing this pr in favour of smaller, markdown esc prs for these pages 👍

@Rumyra Rumyra closed this Sep 20, 2021
@Rumyra Rumyra reopened this Sep 21, 2021
@Rumyra Rumyra closed this Sep 21, 2021
---
<div>{{JSRef}}</div>

<p>The <code><strong>AsyncGenerator</strong></code> object is returned by an {{jsxref("Statements/async_function*", "async generator function", "", 1)}} and it conforms to both the <a href="/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol">iterable protocol</a> and the <a href="/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol">iterator protocol</a>.</p>
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After reading the specification some more, I noticed that we may have made a copying error here when saying that it “conforms to both the iterable protocol and iterator protocol”, since it seems to actually conform to the async iterable protocol and async iterator protocol

Refs: https://tc39.es/ecma262/#sec-asyncgenerator-objects

We should ensure that this is corrected in the PR that adds this page.

Unfortunately, it seems like MDN is missing pages for those protocols (previous links make no mention)…

/cc @Rumyra

@github-actions github-actions bot locked as resolved and limited conversation to collaborators Sep 21, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Content:JS JavaScript docs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[JavaScript] Document “AsyncGenerator” & “AsyncGeneratorFunction”
7 participants