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

Add "promise" doc alias to async keyword #79211

Merged
merged 1 commit into from Dec 19, 2020

Conversation

yoshuawuyts
Copy link
Member

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
Copy link
Collaborator

r? @Mark-Simulacrum

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

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Nov 19, 2020
@Mark-Simulacrum
Copy link
Member

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.

@Mark-Simulacrum Mark-Simulacrum added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Nov 22, 2020
@yoshuawuyts
Copy link
Member Author

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
Copy link
Member

@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
Copy link
Member Author

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

@GuillaumeGomez GuillaumeGomez added A-doc-alias Area: #[doc(alias)] A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Dec 4, 2020
@GuillaumeGomez
Copy link
Member

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
Copy link
Member

(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
Copy link
Member

GuillaumeGomez commented Dec 4, 2020

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
Copy link
Member

Manishearth commented Dec 4, 2020

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
Copy link
Member

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
Copy link
Member

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
Copy link
Member

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
Copy link
Member Author

yoshuawuyts commented Dec 18, 2020

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
Copy link
Member

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

@bors r+ rollup

@bors
Copy link
Contributor

bors commented Dec 18, 2020

📌 Commit 48d5874 has been approved by Mark-Simulacrum

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Dec 18, 2020
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request Dec 19, 2020
…k-Simulacrum

Add the "async" and "promise" doc aliases to `core::future::Future`

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!
bors added a commit to rust-lang-ci/rust that referenced this pull request Dec 19, 2020
Rollup of 7 pull requests

Successful merges:

 - rust-lang#78083 (Stabilize or_insert_with_key)
 - rust-lang#79211 (Add the "async" and "promise" doc aliases to `core::future::Future`)
 - rust-lang#79612 (Switch some links in compiler/ to intra-doc links)
 - rust-lang#80068 (Add `&mut` as an alias for 'reference' primitive)
 - rust-lang#80129 (docs: Edit rustc_ast::token::Token)
 - rust-lang#80133 (Suppress `CONST_ITEM_MUTATION` lint if a dereference occurs anywhere)
 - rust-lang#80155 (Fix typo)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit 60aad47 into rust-lang:master Dec 19, 2020
@rustbot rustbot added this to the 1.50.0 milestone Dec 19, 2020
@jyn514 jyn514 changed the title Add the "async" and "promise" doc aliases to core::future::Future Add "promise" doc alias to async keyword Dec 19, 2020
@yoshuawuyts yoshuawuyts deleted the future-doc-alias branch December 21, 2020 23:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-doc-alias Area: #[doc(alias)] A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

8 participants