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> {

futures-util/src/future/join.rs

@@ -68,27 +68,15 @@ macro_rules! generate {
 }
 
 generate! {
-    /// Future for the `join` combinator, waiting for two futures to
-    /// complete.
-    ///
-    /// This is created by the `Future::join` method.
+    /// Future for the [`join`](super::FutureExt::join) combinator.
     (Join, <Fut1, Fut2>),
 
-    /// Future for the `join3` combinator, waiting for three futures to
-    /// complete.
-    ///
-    /// This is created by the `Future::join3` method.
+    /// Future for the [`join3`](super::FutureExt::join3) combinator.
     (Join3, <Fut1, Fut2, Fut3>),
 
-    /// Future for the `join4` combinator, waiting for four futures to
-    /// complete.
-    ///
-    /// This is created by the `Future::join4` method.
+    /// Future for the [`join4`](super::FutureExt::join4) combinator.
     (Join4, <Fut1, Fut2, Fut3, Fut4>),
 
-    /// Future for the `join5` combinator, waiting for five futures to
-    /// complete.
-    ///
-    /// This is created by the `Future::join5` method.
+    /// Future for the [`join5`](super::FutureExt::join5) combinator.
     (Join5, <Fut1, Fut2, Fut3, Fut4, Fut5>),
 }

futures-util/src/future/join_all.rs

@@ -55,10 +55,7 @@ fn iter_pin_mut<T>(slice: Pin<&mut [T]>) -> impl Iterator<Item = Pin<&mut T>> {
         .map(|t| unsafe { Pin::new_unchecked(t) })
 }
 
-/// A future which takes a list of futures and resolves with a vector of the
-/// completed values.
-///
-/// This future is created with the `join_all` function.
+/// Future for the [`join_all`] combinator.
 #[must_use = "futures do nothing unless polled"]
 pub struct JoinAll<F>
 where

futures-util/src/future/lazy.rs

@@ -2,9 +2,7 @@ use core::pin::Pin;
 use futures_core::future::{FusedFuture, Future};
 use futures_core::task::{Waker, Poll};
 
-/// A future which, when polled, invokes a closure and yields its result.
-///
-/// This is created by the [`lazy()`] function.
+/// Future for the [`lazy`] combinator.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct Lazy<F> {

futures-util/src/future/map.rs

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

futures-util/src/future/poll_fn.rs

@@ -4,9 +4,7 @@ use core::pin::Pin;
 use futures_core::future::Future;
 use futures_core::task::{Waker, Poll};
 
-/// A future which wraps a function returning [`Poll`].
-///
-/// Created by the [`poll_fn()`] function.
+/// Future for the [`poll_fn`] combinator.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct PollFn<F> {

futures-util/src/future/ready.rs

@@ -2,9 +2,7 @@ use core::pin::Pin;
 use futures_core::future::{FusedFuture, Future};
 use futures_core::task::{Waker, Poll};
 
-/// A future that is immediately ready with a value
-///
-/// Created by the [`ready()`] function.
+/// Future for the [`ready`](ready()) combinator.
 #[derive(Debug, Clone)]
 #[must_use = "futures do nothing unless polled"]
 pub struct Ready<T>(Option<T>);

futures-util/src/future/shared.rs

@@ -9,9 +9,7 @@ use std::sync::atomic::AtomicUsize;
 use std::sync::atomic::Ordering::SeqCst;
 use std::sync::{Arc, Mutex};
 
-/// A future that is cloneable and can be polled in multiple threads.
-/// Use the [`shared`](crate::FutureExt::shared) combinator method to convert
-/// any future into a `Shared` future.
+/// Future for the [`shared`](super::FutureExt::shared) combinator.
 #[must_use = "futures do nothing unless polled"]
 pub struct Shared<Fut: Future> {
     inner: Option<Arc<Inner<Fut>>>,

futures-util/src/future/then.rs

@@ -4,10 +4,7 @@ use futures_core::future::{FusedFuture, Future};
 use futures_core::task::{Waker, Poll};
 use pin_utils::unsafe_pinned;
 
-/// Future for the `then` combinator, chaining computations on the end of
-/// another future regardless of its outcome.
-///
-/// This is created by the `Future::then` method.
+/// Future for the [`then`](super::FutureExt::then) combinator.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct Then<Fut1, Fut2, F> {

futures-util/src/io/close.rs

@@ -4,11 +4,7 @@ use futures_io::AsyncWrite;
 use std::io;
 use std::pin::Pin;
 
-/// A future used to fully close an I/O object.
-///
-/// Created by the [`close`] function.
-///
-/// [`close`]: fn.close.html
+/// Future for the [`close`](super::AsyncWriteExt::close) combinator.
 #[derive(Debug)]
 pub struct Close<'a, W: ?Sized + Unpin> {
     writer: &'a mut W,

futures-util/src/io/copy_into.rs

@@ -5,12 +5,7 @@ use std::boxed::Box;
 use std::io;
 use std::pin::Pin;
 
-/// A future which will copy all data from a reader into a writer.
-///
-/// Created by the [`copy_into`] function, this future will resolve to the number of
-/// bytes copied or an error if one happens.
-///
-/// [`copy_into`]: fn.copy_into.html
+/// Future for the [`copy_into`](super::AsyncReadExt::copy_into) combinator.
 #[derive(Debug)]
 pub struct CopyInto<'a, R: ?Sized + Unpin, W: ?Sized + Unpin> {
     reader: &'a mut R,

futures-util/src/io/flush.rs

@@ -4,13 +4,7 @@ use futures_io::AsyncWrite;
 use std::io;
 use std::pin::Pin;
 
-/// A future used to fully flush an I/O object.
-///
-/// Resolves to the underlying I/O object once the flush operation is complete.
-///
-/// Created by the [`flush`] function.
-///
-/// [`flush`]: fn.flush.html
+/// Future for the [`flush`](super::AsyncWriteExt::flush) combinator.
 #[derive(Debug)]
 pub struct Flush<'a, W: ?Sized + Unpin> {
     writer: &'a mut W,

futures-util/src/io/read.rs

@@ -4,8 +4,7 @@ use futures_core::task::{Waker, Poll};
 use std::io;
 use std::pin::Pin;
 
-/// A future which can be used to easily read available number of bytes to fill
-/// a buffer.
+/// Future for the [`read`](super::AsyncReadExt::read) combinator.
 #[derive(Debug)]
 pub struct Read<'a, R: ?Sized + Unpin> {
     reader: &'a mut R,

futures-util/src/io/read_exact.rs

@@ -5,12 +5,7 @@ use std::io;
 use std::mem;
 use std::pin::Pin;
 
-/// A future which can be used to easily read exactly enough bytes to fill
-/// a buffer.
-///
-/// Created by the [`read_exact`] function.
-///
-/// [`read_exact`]: fn.read_exact.html
+/// Future for the [`read_exact`](super::AsyncReadExt::read_exact) combinator.
 #[derive(Debug)]
 pub struct ReadExact<'a, R: ?Sized + Unpin> {
     reader: &'a mut R,

futures-util/src/io/read_to_end.rs

@@ -5,12 +5,7 @@ use std::io;
 use std::pin::Pin;
 use std::vec::Vec;
 
-/// A future which can be used to easily read the entire contents of a stream
-/// into a vector.
-///
-/// Created by the [`read_to_end`] function.
-///
-/// [`read_to_end`]: fn.read_to_end.html
+/// Future for the [`read_to_end`](super::AsyncReadExt::read_to_end) combinator.
 #[derive(Debug)]
 pub struct ReadToEnd<'a, R: ?Sized + Unpin> {
     reader: &'a mut R,

futures-util/src/io/write_all.rs

@@ -5,11 +5,7 @@ use std::io;
 use std::mem;
 use std::pin::Pin;
 
-/// A future used to write the entire contents of some data to a stream.
-///
-/// This is created by the [`write_all`] top-level method.
-///
-/// [`write_all`]: fn.write_all.html
+/// Future for the [`write_all`](super::AsyncWriteExt::write_all) combinator.
 #[derive(Debug)]
 pub struct WriteAll<'a, W: ?Sized + Unpin> {
     writer: &'a mut W,

futures-util/src/sink/buffer.rs

@@ -5,8 +5,7 @@ use pin_utils::{unsafe_pinned, unsafe_unpinned};
 use core::pin::Pin;
 use alloc::collections::VecDeque;
 
-/// Sink for the `Sink::buffer` combinator, which buffers up to some fixed
-/// number of values when the underlying sink is unable to accept them.
+/// Sink for the [`buffer`](super::SinkExt::buffer) combinator.
 #[derive(Debug)]
 #[must_use = "sinks do nothing unless polled"]
 pub struct Buffer<Si: Sink<Item>, Item> {

futures-util/src/sink/close.rs

@@ -4,8 +4,7 @@ use futures_core::future::Future;
 use futures_core::task::{Waker, Poll};
 use futures_sink::Sink;
 
-/// Future for the `close` combinator, which polls the sink until all data has
-/// been closed.
+/// Future for the [`close`](super::SinkExt::close) combinator.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct Close<'a, Si: Sink<Item> + Unpin + ?Sized, Item> {

futures-util/src/sink/drain.rs

@@ -4,9 +4,7 @@ use core::pin::Pin;
 use futures_core::task::{Waker, Poll};
 use futures_sink::Sink;
 
-/// A sink that will discard all items given to it.
-///
-/// See the [`drain()`] function for more details.
+/// Sink for the [`drain`] combinator.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct Drain<T> {

futures-util/src/sink/err_into.rs

@@ -5,9 +5,7 @@ use futures_core::task::{Waker, Poll};
 use futures_sink::{Sink};
 use pin_utils::unsafe_pinned;
 
-/// A sink combinator to change the error type of a sink.
-///
-/// This is created by the `Sink::err_into` method.
+/// Sink for the [`sink_err_into`](super::SinkExt::sink_err_into) combinator.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct SinkErrInto<Si: Sink<Item>, Item, E> {

futures-util/src/sink/flush.rs

@@ -4,8 +4,7 @@ use futures_core::future::Future;
 use futures_core::task::{Waker, Poll};
 use futures_sink::Sink;
 
-/// Future for the `flush` combinator, which polls the sink until all data
-/// has been flushed.
+/// Future for the [`flush`](super::SinkExt::flush) combinator.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct Flush<'a, Si: Sink<Item> + Unpin + ?Sized, Item> {

futures-util/src/sink/map_err.rs

@@ -4,7 +4,7 @@ use futures_core::task::{Waker, Poll};
 use futures_sink::{Sink};
 use pin_utils::{unsafe_pinned, unsafe_unpinned};
 
-/// Sink for the `Sink::sink_map_err` combinator.
+/// Sink for the [`sink_map_err`](super::SinkExt::sink_map_err) combinator.
 #[derive(Debug)]
 #[must_use = "sinks do nothing unless polled"]
 pub struct SinkMapErr<Si, F> {

futures-util/src/sink/send.rs

@@ -3,8 +3,7 @@ use futures_core::future::Future;
 use futures_core::task::{Waker, Poll};
 use futures_sink::Sink;
 
-/// Future for the `Sink::send` combinator, which sends a value to a sink and
-/// then waits until the sink has fully flushed.
+/// Future for the [`send`](super::SinkExt::send) combinator.
 #[derive(Debug)]
 #[must_use = "futures do nothing unless polled"]
 pub struct Send<'a, Si: Sink<Item> + Unpin + ?Sized, Item> {