Work on docs and examples for free future functions

futures-util/src/future/empty.rs

@@ -1,13 +1,11 @@
-//! Definition of the Empty combinator, a future that's never ready.
-
 use core::marker;
 use core::mem::PinMut;
 use futures_core::future::Future;
 use futures_core::task::{self, Poll};
 
 /// A future which is never resolved.
 ///
-/// This future can be created with the `empty` function.
+/// This future can be created with the [`empty()`] function.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct Empty<T> {
@@ -17,7 +15,20 @@ pub struct Empty<T> {
 /// Creates a future which never resolves, representing a computation that never
 /// finishes.
 ///
-/// The returned future will forever return `Async::Pending`.
+/// The returned future will forever return [`Poll::Pending`].
+///
+/// # Examples
+///
+/// ```ignore
+/// #![feature(async_await, await_macro, futures_api)]
+/// # futures::executor::block_on(async {
+/// use futures::future;
+///
+/// let future = future::empty();
+/// let () = await!(future);
+/// unreachable!();
+/// # });
+/// ```
 pub fn empty<T>() -> Empty<T> {
     Empty { _data: marker::PhantomData }
 }

futures-util/src/future/lazy.rs

@@ -1,14 +1,11 @@
-//! Definition of the Lazy combinator, deferring execution of a function until
-//! the future is polled.
-
 use core::marker::Unpin;
 use core::mem::PinMut;
 use futures_core::future::Future;
 use futures_core::task::{self, Poll};
 
 /// A future which, when polled, invokes a closure and yields its result.
 ///
-/// This is created by the `lazy` function.
+/// This is created by the [`lazy()`] function.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct Lazy<F> {
@@ -18,25 +15,25 @@ pub struct Lazy<F> {
 // safe because we never generate `PinMut<F>`
 impl<F> Unpin for Lazy<F> {}
 
-/// Creates a new future from a closure.
+/// Creates a new future that allows delayed execution of a closure.
 ///
 /// The provided closure is only run once the future is polled.
 ///
 /// # Examples
 ///
 /// ```
-/// # extern crate futures;
-/// use futures::prelude::*;
+/// #![feature(async_await, await_macro, futures_api)]
+/// # futures::executor::block_on(async {
 /// use futures::future;
 ///
-/// # fn main() {
 /// let a = future::lazy(|_| 1);
+/// assert_eq!(await!(a), 1);
 ///
 /// let b = future::lazy(|_| -> i32 {
 ///     panic!("oh no!")
 /// });
 /// drop(b); // closure is never run
-/// # }
+/// # });
 /// ```
 pub fn lazy<F, R>(f: F) -> Lazy<F>
     where F: FnOnce(&mut task::Context) -> R,

futures-util/src/future/maybe_done.rs

@@ -5,24 +5,40 @@ use core::mem::{self, PinMut};
 use futures_core::future::Future;
 use futures_core::task::{self, Poll};
 
-/// `MaybeDone`, a future that may have completed.
+/// A future that may have completed.
 ///
-/// This is created by the `maybe_done` function.
+/// This is created by the [`maybe_done()`] function.
 #[derive(Debug)]
 pub enum MaybeDone<Fut: Future> {
     /// A not-yet-completed future
     Future(Fut),
     /// The output of the completed future
     Done(Fut::Output),
-    /// The empty variant after the result of a `maybe_done` has been
-    /// taken using the `take_output` method.
+    /// The empty variant after the result of a [`MaybeDone`] has been
+    /// taken using the [`take_output`](MaybeDone::take_output) method.
     Gone,
 }
 
 // Safe because we never generate `PinMut<Fut::Output>`
 impl<Fut: Future + Unpin> Unpin for MaybeDone<Fut> {}
 
-/// Creates a new future from a closure.
+/// Wraps a future into a `MaybeDone`
+///
+/// # Examples
+///
+/// ```
+/// #![feature(async_await, await_macro, futures_api, use_extern_macros, pin)]
+/// # futures::executor::block_on(async {
+/// use futures::{future, pin_mut};
+///
+/// let future = future::maybe_done(future::ready(5));
+/// pin_mut!(future);
+/// assert_eq!(future.reborrow().take_output(), None);
+/// let () = await!(future.reborrow());
+/// assert_eq!(future.reborrow().take_output(), Some(5));
+/// assert_eq!(future.reborrow().take_output(), None);
+/// # });
+/// ```
 pub fn maybe_done<Fut: Future>(future: Fut) -> MaybeDone<Fut> {
     MaybeDone::Future(future)
 }

futures-util/src/future/option.rs

@@ -6,14 +6,21 @@ use core::mem::PinMut;
 
 /// A future representing a value which may or may not be present.
 ///
-/// Created by the `From` implementation for `std::option::Option`.
+/// Created by the [`From`] implementation for [`Option`](std::option::Option).
+///
+/// # Examples
 ///
 /// ```
-/// # extern crate futures;
-/// use futures::prelude::*;
-/// use futures::future::OptionFuture;
+/// #![feature(async_await, await_macro, futures_api)]
+/// # futures::executor::block_on(async {
+/// use futures::future::{self, OptionFuture};
+///
+/// let mut a: OptionFuture<_> = Some(future::ready(123)).into();
+/// assert_eq!(await!(a), Some(123));
 ///
-/// let fut: OptionFuture<_> = Some(123).into();
+/// a = None.into();
+/// assert_eq!(await!(a), None);
+/// # });
 /// ```
 #[derive(Debug, Clone)]
 #[must_use = "futures do nothing unless polled"]

futures-util/src/future/poll_fn.rs

@@ -5,32 +5,34 @@ use core::mem::PinMut;
 use futures_core::future::Future;
 use futures_core::task::{self, Poll};
 
-/// A future which adapts a function returning `Poll`.
+/// A future which wraps a function returning [`Poll`].
 ///
-/// Created by the `poll_fn` function.
+/// Created by the [`poll_fn()`] function.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct PollFn<F> {
     f: F,
 }
 
-/// Creates a new future wrapping around a function returning `Poll`.
+/// Creates a new future wrapping around a function returning [`Poll`].
 ///
 /// Polling the returned future delegates to the wrapped function.
 ///
 /// # Examples
 ///
 /// ```
-/// # #![feature(futures_api)]
-/// # extern crate futures;
-/// use futures::prelude::*;
+/// #![feature(async_await, await_macro, futures_api)]
+/// # futures::executor::block_on(async {
 /// use futures::future::poll_fn;
+/// use futures::task::{self, Poll};
 ///
 /// fn read_line(cx: &mut task::Context) -> Poll<String> {
 ///     Poll::Ready("Hello, World!".into())
 /// }
 ///
 /// let read_future = poll_fn(read_line);
+/// assert_eq!(await!(read_future), "Hello, World!".to_owned());
+/// # });
 /// ```
 pub fn poll_fn<T, F>(f: F) -> PollFn<F>
     where F: Unpin + FnMut(&mut task::Context) -> Poll<T>

futures-util/src/future/ready.rs

@@ -4,6 +4,8 @@ use futures_core::future::Future;
 use futures_core::task::{self, Poll};
 
 /// A future that is immediately ready with a value
+///
+/// Created by the [`ready()`] function.
 #[derive(Debug, Clone)]
 #[must_use = "futures do nothing unless polled"]
 pub struct Ready<T>(Option<T>);
@@ -20,6 +22,18 @@ impl<T> Future for Ready<T> {
 }
 
 /// Create a future that is immediately ready with a value.
+///
+/// # Examples
+///
+/// ```
+/// #![feature(async_await, await_macro, futures_api)]
+/// # futures::executor::block_on(async {
+/// use futures::future;
+///
+/// let a = future::ready(1);
+/// assert_eq!(await!(a), 1);
+/// # });
+/// ```
 pub fn ready<T>(t: T) -> Ready<T> {
     Ready(Some(t))
 }