Some improvements to the async docs · rust-lang/rust@297364e (original) (raw)

3 files changed

lines changed

Original file line number Diff line number Diff line change
@@ -5,7 +5,7 @@ use crate::ops;
5 5 use crate::pin::Pin;
6 6 use crate::task::{Context, Poll};
7 7
8 -/// A future represents an asynchronous computation.
8 +/// A future represents an asynchronous computation obtained by use of [`async`].
9 9 ///
10 10 /// A future is a value that might not have finished computing yet. This kind of
11 11 /// "asynchronous value" makes it possible for a thread to continue doing useful
@@ -23,6 +23,7 @@ use crate::task::{Context, Poll};
23 23 /// When using a future, you generally won't call `poll` directly, but instead
24 24 /// `.await` the value.
25 25 ///
26 +/// [`async`]: ../../std/keyword.async.html
26 27 /// [`Waker`]: crate::task::Waker
27 28 #[doc(notable_trait)]
28 29 #[must_use = "futures do nothing unless you `.await` or poll them"]
Original file line number Diff line number Diff line change
@@ -1,6 +1,13 @@
1 1 #![stable(feature = "futures_api", since = "1.36.0")]
2 2
3 -//! Asynchronous values.
3 +//! Asynchronous basic functionality.
4 +//!
5 +//! Please see the fundamental [`async`] and [`await`] keywords and the [async book]
6 +//! for more information on asynchronous programming in Rust.
7 +//!
8 +//! [`async`]: ../../std/keyword.async.html
9 +//! [`await`]: ../../std/keyword.await.html
10 +//! [async book]: https://rust-lang.github.io/async-book/
4 11
5 12 use crate::{
6 13 ops::{Generator, GeneratorState},
Original file line number Diff line number Diff line change
@@ -2203,37 +2203,39 @@ mod where_keyword {}
2203 2203 ///
2204 2204 /// Use `async` in front of `fn`, `closure`, or a `block` to turn the marked code into a `Future`.
2205 2205 /// As such the code will not be run immediately, but will only be evaluated when the returned
2206 -/// future is `.await`ed.
2206 +/// future is [`.await`]ed.
2207 2207 ///
2208 -/// We have written an [async book] detailing async/await and trade-offs compared to using threads.
2208 +/// We have written an [async book] detailing `async`/`await` and trade-offs compared to using threads.
2209 2209 ///
2210 2210 /// ## Editions
2211 2211 ///
2212 2212 /// `async` is a keyword from the 2018 edition onwards.
2213 2213 ///
2214 -/// It is available for use in stable rust from version 1.39 onwards.
2214 +/// It is available for use in stable Rust from version 1.39 onwards.
2215 2215 ///
2216 2216 /// [`Future`]: future::Future
2217 +/// [`.await`]: ../std/keyword.await.html
2217 2218 /// [async book]: https://rust-lang.github.io/async-book/
2218 2219 mod async_keyword {}
2219 2220
2220 2221 #[doc(keyword = "await")]
2221 2222 //
2222 2223 /// Suspend execution until the result of a [`Future`] is ready.
2223 2224 ///
2224 -/// `.await`ing a future will suspend the current function's execution until the `executor`
2225 +/// `.await`ing a future will suspend the current function's execution until the executor
2225 2226 /// has run the future to completion.
2226 2227 ///
2227 -/// Read the [async book] for details on how async/await and executors work.
2228 +/// Read the [async book] for details on how [`async`]/`await` and executors work.
2228 2229 ///
2229 2230 /// ## Editions
2230 2231 ///
2231 2232 /// `await` is a keyword from the 2018 edition onwards.
2232 2233 ///
2233 -/// It is available for use in stable rust from version 1.39 onwards.
2234 +/// It is available for use in stable Rust from version 1.39 onwards.
2234 2235 ///
2235 2236 /// [`Future`]: future::Future
2236 2237 /// [async book]: https://rust-lang.github.io/async-book/
2238 +/// [`async`]: ../std/keyword.async.html
2237 2239 mod await_keyword {}
2238 2240
2239 2241 #[doc(keyword = "dyn")]