async-await keywords are not documented in the libstd docs

[ultrasaurus]

I have a PR for this, just opening an issue, since I might be missing other parts of it.

I couldn't find up-to-date docs on the new async / await keywords. Std library docs have blank pages:

• https://doc.rust-lang.org/std/keyword.async.html
• https://doc.rust-lang.org/std/keyword.await.html

Perhaps there are other docs somewhere, but I thought to look at the RFC. The tracking bug is closed, but the RFC is not fully implemented.

[ehuss]

Just FYI, the current documentation is:

• reference:
  • await expressions: https://doc.rust-lang.org/nightly/reference/expressions/await-expr.html
  • async functions: https://doc.rust-lang.org/nightly/reference/items/functions.html#async-functions
  • async blocks: https://doc.rust-lang.org/nightly/reference/expressions/block-expr.html#async-blocks
• async book: https://rust-lang.github.io/async-book/index.html

[nikomatsakis]

@ultrasaurus did you say you have a PR for adding the docs? Good catch, I wasn't aware of that documentation.

I've retitled this to suggest the specific oversight, and I'm tagged as "on deck" as it seems worth fixing (and not very difficult).

[ultrasaurus]

@nikomatsakis I made a super simple PR to RFC repo (rust-lang/rfcs#2828) that hasn't been reviewed yet.

I'm still working my way through the docs on async / await and am not the one to judge whether the docs in nightly are ready to be merged, just flagging that async / await are now in stable ... was it an error that docs weren't merged? if intentional, then a link to nightly docs and/or RFC would be great.

[nikomatsakis]

@ultrasaurus I see. OK, I've closed that PR since that's not our usual procedure. This is a fairly minor matter from what I can tell, I thnk we mostly would want to include some text and link to the docs in the reference for more details. (I don't think the nightly docs or RFC are especially relevant to link to.) The real question is where in the source code you go to add documentation on keywords -- probably @GuillaumeGomez would be able to answer that question.

[nikomatsakis]

@rustbot assign @gilescope

@gilescope indicated a willingness to take this one. My suggestion would be to ripgrep through the source to find where e.g. the documentation for the keyword const is to be found and then add comparable documentation for async. It could either borrow some text from the existing documentation or simply provide some links to that.

[GuillaumeGomez]

Sorry, didn't see the notification... If you want to add docs for keyword, you can look here: https://github.com/rust-lang/rust/blob/master/src/libstd/keyword_docs.rs