document the stabilized surface of async-await

[nikomatsakis]

This issue is part of async-await stabilization (see rust-lang/rust#62149). We need to document the following things:

• grammar for async fn and describe their effects
• grammar for async move { } blocks
• grammar for await expressions, and describe the "rough" desugaring
• link to the drop order when that is fully documented

[nikomatsakis]

I am taking a first pass at this.

[alercah]

Async closures are missing.

[nikomatsakis]

Async closures are not stabilized, and this issue was specific to stabilized surface area -- actually, I think we can probably close this? I'm not sure what I meant by 'document the drop order'.

[nikomatsakis]

@cramertj or @withoutboats do you have any idea what I might have meant by "link to drop order when that is stabilized"?

I do know that @matthewjasper recently opened a PR about #514 drop scopes which I think mentioned something about drop order here...

[alercah]

They're not stabilized? Why does https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=3795067a2d54b2d90a5d807eed51a93e work then?

…

On Thu., Apr. 16, 2020, 12:32 Niko Matsakis, ***@***.***> wrote: @cramertj <https://github.com/cramertj> or @withoutboats <https://github.com/withoutboats> do you have any idea what I might have meant by "link to drop order when that is stabilized"? I do know that @matthewjasper <https://github.com/matthewjasper> recently opened a PR about #514 <#514> drop scopes which I think mentioned something about drop order here... — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#634 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AE7AOVIFMLPRBMXT4226ZX3RM4XKVANCNFSM4H7SDZSQ> .

[cramertj]

I would guess the drop order bit has to do with the changes we made around when _ arguments to async functions get dropped.

[kpreid]

Another thing that is currently undocumented is async block/fn future types, as types. I filed #1555 for that.