Add "promise" doc alias to async keyword

[yoshuawuyts]

Adds the "async" and "promise" doc aliases to core::future::Future. This enables people who search for "async" or "promise" to find Future, which is Rust's core primitive for async programming. Thanks!

[rust-highfive]

r? @Mark-Simulacrum

(rust_highfive has picked a reviewer for you, use r? to override)

[Mark-Simulacrum]

Hm, it's a bit unfortunate there's not a page in the rustdoc that we can link to (maybe std::task or std::future should be it?) which tries to lay out the things you want to know about when working with Futures, e.g., that implementing the Future trait is unlikely to be the right approach. At least I wouldn't want people to land on the current docs for Future with JS promise context, because they're pretty unhelpful in that regard, if you're coming from JS you want async {} or async fn most likely, not the Future trait really.

I note that https://doc.rust-lang.org/nightly/std/keyword.async.html seems like maybe a better place for these aliases to point at.

[yoshuawuyts]

I note that https://doc.rust-lang.org/nightly/std/keyword.async.html seems like maybe a better place for these aliases to point at.

I think that's fair. I was thinking perhaps std::future as well; but at the keyword-layer we can dive into more detail on everything async, rather than just Future (async IO and iteration are expected to be added later too). We can then backlink from the std::future docs to the async (keyword) docs. That's a great suggestion; going to change that up.

[joshtriplett]

@yoshuawuyts I agree that linking to the keyword seems preferable.

I would also suggest, if you're going to add an alias for promise, that there should be a paragraph in that documentation explaining that some languages call this a "promise", but explaining the core difference between futures and promises (futures don't run when called, they run when awaited; promises, in some languages, run immediately when called and just block on the result when awaited).

[yoshuawuyts]

@joshtriplett that's a good suggestion; will do!

[GuillaumeGomez]

Considering it's doc changes, please ping the @rust-lang/docs (or the @rust-lang/rustdoc) teams in the future. Strongly like the idea though!

[Manishearth]

(I actually don't think the rustdoc team should be pinged for doc aliases, that's libs team stuff. Once a rustdoc feature exists, it's up to the individual teams as to whete it gets used in their library)

[GuillaumeGomez]

No you're right, with some steps back the rustdoc team doesn't have its word to say. However, at least pinging the doc team seems, even though if their approval isn't required seems like a valid point (and tagging as doc-alias too).

[Manishearth]

The doc team doesn't really exist anymore as a general doc team, the idea is that individual teams manage their own docs; so libs manages stdlib docs.

[GuillaumeGomez]

Well, the std lib documentation is the public documentation so it's definitely part of whatever remains of the doc team. So please ping the doc team (or me?).

[Manishearth]

Well, the std lib documentation is the public documentation so it's definitely part of whatever remains of the doc team. So please ping the doc team (or me?).

This advice is outdated, i'll explain more on discord. The stdlib documentation is handled by the libs team.

[GuillaumeGomez]

Considering how much I contributed to both the stdlib docs and the feature being used, it doesn't kill to at least ping me (or the docs team) so that I'm (we are) aware of it. And it can help help to simply have a second point of view sometimes. Also, it's nice to see that what I worked on is being used widely. :)

[yoshuawuyts]

I've updated the PR to point the promise alias to the async lang feature instead. I'm not sure what we should add to the async docs, as it feels we could probably borrow a lot from the async book. So I'd like to propose we follow up on improving the async lang feature documentation in another PR.

[Mark-Simulacrum]

Oh, having the async book linked already seems like a great way to me :)

@bors r+ rollup

[bors]

📌 Commit 48d5874 has been approved by Mark-Simulacrum