Unify the style of combinator type descriptions

Author: taiki-e

futures-util/src/future/catch_unwind.rs

@@ -6,9 +6,7 @@ use std::pin::Pin;
 use std::panic::{catch_unwind, UnwindSafe, AssertUnwindSafe};
 use std::prelude::v1::*;
 
-/// Future for the `catch_unwind` combinator.
-///
-/// This is created by the `Future::catch_unwind` method.
+/// Future for the [`catch_unwind`](super::FutureExt::catch_unwind) combinator.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct CatchUnwind<Fut> where Fut: Future {

futures-util/src/future/disabled/select.rs

@@ -3,12 +3,7 @@ use futures_core::task;
 
 use either::Either;
 
-/// Future for the `select` combinator, waiting for one of two differently-typed
-/// futures to complete.
-///
-/// This is created by the [`Future::select`] method.
-///
-/// [`Future::select`]: trait.Future.html#method.select
+/// Future for the [`select`](super::FutureExt::select) combinator.
 #[must_use = "futures do nothing unless polled"]
 #[derive(Debug)]
 pub struct Select<A, B> {

futures-util/src/future/disabled/select_all.rs

@@ -7,10 +7,7 @@ use std::prelude::v1::*;
 use futures_core::{Future, IntoFuture, Poll, Async};
 use futures_core::task;
 
-/// Future for the `select_all` combinator, waiting for one of any of a list of
-/// futures to complete.
-///
-/// This is created by the `select_all` function.
+/// Future for the [`select_all`] combinator.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct SelectAll<A> where A: Future {

futures-util/src/future/disabled/select_ok.rs

@@ -7,11 +7,7 @@ use std::prelude::v1::*;
 use futures_core::{Future, IntoFuture, Poll, Async};
 use futures_core::task;
 
-/// Future for the `select_ok` combinator, waiting for one of any of a list of
-/// futures to successfully complete. Unlike `select_all`, this future ignores all
-/// but the last error, if there are any.
-///
-/// This is created by the `select_ok` function.
+/// Future for the [`select_ok`] combinator.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct SelectOk<A> where A: Future {

futures-util/src/future/empty.rs

@@ -3,9 +3,7 @@ use core::pin::Pin;
 use futures_core::future::{Future, FusedFuture};
 use futures_core::task::{Waker, Poll};
 
-/// A future which is never resolved.
-///
-/// This future can be created with the [`empty()`] function.
+/// Future for the [`empty`] combinator.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct Empty<T> {

futures-util/src/future/flatten.rs

@@ -5,11 +5,7 @@ use futures_core::future::{FusedFuture, Future};
 use futures_core::task::{Waker, Poll};
 use pin_utils::unsafe_pinned;
 
-/// Future for the `flatten` combinator.
-///
-/// This combinator turns a `Future`-of-a-`Future` into a single `Future`.
-///
-/// This is created by the `Future::flatten` method.
+/// Future for the [`flatten`](super::FutureExt::flatten) combinator.
 #[must_use = "futures do nothing unless polled"]
 pub struct Flatten<Fut>
     where Fut: Future,

futures-util/src/future/flatten_stream.rs

@@ -4,10 +4,8 @@ use futures_core::future::Future;
 use futures_core::stream::{FusedStream, Stream};
 use futures_core::task::{Waker, Poll};
 
-/// Future for the `flatten_stream` combinator, flattening a
-/// future-of-a-stream to get just the result of the final stream as a stream.
-///
-/// This is created by the `Future::flatten_stream` method.
+/// Stream for the [`flatten_stream`](super::FutureExt::flatten_stream)
+/// combinator.
 #[must_use = "streams do nothing unless polled"]
 pub struct FlattenStream<Fut: Future> {
     state: State<Fut>

futures-util/src/future/fuse.rs

@@ -3,15 +3,7 @@ use futures_core::future::{Future, FusedFuture};
 use futures_core::task::{Waker, Poll};
 use pin_utils::unsafe_pinned;
 
-/// A future which "fuses" a future once it has been resolved.
-/// This wrapper can be used to turn any `Future` into a `FusedFuture`.
-///
-/// Normally, `poll`ing a future after it has completed (returned `Poll::Ready`
-/// from a call to `poll`) can cause arbitrary behavior (panics, deadlock).
-/// `Fuse` is always defined to return `Poll::Pending` from `poll` after it has
-/// resolved.
-///
-/// This is created by the `Future::fuse` method.
+/// Future for the [`fuse`](super::FutureExt::fuse) combinator.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct Fuse<Fut: Future> {

futures-util/src/future/inspect.rs

@@ -3,9 +3,7 @@ use futures_core::future::{FusedFuture, Future};
 use futures_core::task::{Waker, Poll};
 use pin_utils::{unsafe_pinned, unsafe_unpinned};
 
-/// Do something with the item of a future, passing it on.
-///
-/// This is created by the [`super::FutureExt::inspect`] method.
+/// Future for the [`inspect`](super::FutureExt::inspect) combinator.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct Inspect<Fut, F> where Fut: Future {

futures-util/src/future/into_stream.rs

@@ -4,8 +4,7 @@ use futures_core::stream::Stream;
 use futures_core::task::{Waker, Poll};
 use pin_utils::unsafe_pinned;
 
-/// A type which converts a `Future` into a `Stream`
-/// containing a single element.
+/// Stream for the [`into_stream`](super::FutureExt::into_stream) combinator.
 #[must_use = "futures do nothing unless polled"]
 #[derive(Debug)]
 pub struct IntoStream<Fut: Future> {