Attempt to fix all documentation warnings from rustdoc.

futures-channel/src/oneshot.rs

@@ -13,7 +13,7 @@ use crate::lock::Lock;
 
 /// A future for a value that will be provided by another asynchronous task.
 ///
-/// This is created by the [`channel`](channel) function.
+/// This is created by the [`channel`] function.
 #[must_use = "futures do nothing unless polled"]
 #[derive(Debug)]
 pub struct Receiver<T> {
@@ -22,7 +22,7 @@ pub struct Receiver<T> {
 
 /// A means of transmitting a single value to another task.
 ///
-/// This is created by the [`channel`](channel) function.
+/// This is created by the [`channel`] function.
 #[derive(Debug)]
 pub struct Sender<T> {
     inner: Arc<Inner<T>>,
@@ -399,7 +399,7 @@ impl<T> Receiver<T> {
     ///
     /// Any `send` operation which happens after this method returns is
     /// guaranteed to fail. After calling this method, you can use
-    /// [`Receiver::poll`](Future::poll) to determine whether a
+    /// [`Receiver::poll`](core::future::Future::poll) to determine whether a
     /// message had previously been sent.
     pub fn close(&mut self) {
         self.inner.close_rx()

futures-core/src/task/spawn.rs

@@ -27,7 +27,7 @@ pub trait Spawn {
     }
 }
 
-/// The `LocalSpawn` is similar to `[Spawn]`, but allows spawning futures
+/// The `LocalSpawn` is similar to [`Spawn`], but allows spawning futures
 /// that don't implement `Send`.
 pub trait LocalSpawn {
     /// Spawns a future that will be run to completion.

futures-executor/src/local_pool.rs

@@ -23,7 +23,7 @@ use std::thread::{self, Thread};
 /// [`Spawn`](futures_core::task::Spawn), use the
 /// [`spawner()`](LocalPool::spawner) method. Because the executor is
 /// single-threaded, it supports a special form of task spawning for non-`Send`
-/// futures, via [`spawn_local_obj`](LocalSpawner::spawn_local_obj).
+/// futures, via [`spawn_local_obj`](futures_core::task::LocalSpawn::spawn_local_obj).
 #[derive(Debug)]
 pub struct LocalPool {
     pool: FuturesUnordered<LocalFutureObj<'static, ()>>,

futures-test/src/task/mod.rs

@@ -1,3 +1,12 @@
+// TODO: note that paths like futures_core::task::Context actually get redirected to core::task::Context
+// in the redered docs. Is this desirable? If so, should we change the paths here?
+//
+// Also, there is cross crate links in here. They are not going to work anytime soon. Do we put https links
+// in here? to here: https://rust-lang-nursery.github.io/futures-api-docs? The problem is these have a
+// version hardcoded in the url: 0.3.0-alpha.15 We could link to docs.rs, but currently that says:
+// docs.rs failed to build futures-preview-0.3.0-alpha.15 -> ok the reason seems to be that they are on
+// 2019-04-17 which does still have futures-api unstable feature, so that should get solved.
+//
 //! Task related testing utilities.
 //!
 //! This module provides utilities for creating test
@@ -6,29 +15,29 @@
 //! [`Spawn`](futures_core::task::Spawn) implementations.
 //!
 //! Test contexts:
-//! - [`noop_context`] creates a context that ignores calls to
+//! - [`noop_context`](crate::task::noop_context) creates a context that ignores calls to
 //!   [`cx.waker().wake_by_ref()`](futures_core::task::Waker).
-//! - [`panic_context`] creates a context that panics when
+//! - [`panic_context`](crate::task::panic_context) creates a context that panics when
 //!   [`cx.waker().wake_by_ref()`](futures_core::task::Waker) is called.
 //!
 //! Test wakers:
-//! - [`noop_waker`] creates a waker that ignores calls to
+//! - [`noop_waker`](crate::task::noop_waker) creates a waker that ignores calls to
 //!   [`wake`](futures_core::task::Waker).
-//! - [`panic_waker`] creates a waker that panics when
+//! - [`panic_waker`](crate::task::panic_waker::panic_waker) creates a waker that panics when
 //!   [`wake`](futures_core::task::Waker) is called.
-//! - [`new_count_waker`] creates a waker that increments a counter whenever
+//! - [`new_count_waker`](crate::task::new_count_waker) creates a waker that increments a counter whenever
 //!   [`wake`](futures_core::task::Waker) is called.
 //!
 //! Test spawners:
-//! - [`NoopSpawner`] ignores calls to
-//!   [`spawn`](futures_core::task::Spawn::spawn)
-//! - [`PanicSpawner`] panics if [`spawn`](futures_core::task::Spawn::spawn) is
+//! - [`NoopSpawner`](crate::task::NoopSpawner) ignores calls to
+//!   [`spawn`](futures_util::task::SpawnExt::spawn)
+//! - [`PanicSpawner`](crate::task::PanicSpawner) panics if [`spawn`](futures_util::task::SpawnExt::spawn) is
 //!   called.
-//! - [`RecordSpawner`] records the spawned futures.
+//! - [`RecordSpawner`](crate::task::RecordSpawner) records the spawned futures.
 //!
 //! For convenience there additionally exist various functions that directly
-//! return waker/spawner references: [`noop_waker_ref`],
-//! [`panic_waker_ref`], [`noop_spawner_mut`] and [`panic_spawner_mut`].
+//! return waker/spawner references: [`noop_waker_ref`](crate::task::noop_waker_ref),
+//! [`panic_waker_ref`](crate::task::panic_waker_ref), [`noop_spawner_mut`](crate::task::noop_spawner_mut) and [`panic_spawner_mut`](crate::task::panic_spawner_mut).
 
 mod context;
 pub use self::context::{noop_context, panic_context};

futures-util/src/future/select.rs

@@ -3,7 +3,7 @@ use futures_core::future::Future;
 use futures_core::task::{Context, Poll};
 use crate::future::Either;
 
-/// Future for the [`select`](super::FutureExt::select) function.
+/// Future for the [`select()`] function.
 #[must_use = "futures do nothing unless polled"]
 #[derive(Debug)]
 pub struct Select<A: Unpin, B: Unpin> {

futures-util/src/io/seek.rs

@@ -4,7 +4,7 @@ use futures_core::task::{Context, Poll};
 use std::io;
 use std::pin::Pin;
 
-/// Future for the [`seek`](super::SeekExt::seek) method.
+/// Future for the [`seek`](crate::io::AsyncSeekExt::seek) method.
 #[derive(Debug)]
 pub struct Seek<'a, S: ?Sized + Unpin> {
     seek: &'a mut S,

futures-util/src/stream/enumerate.rs

@@ -4,7 +4,7 @@ use futures_core::task::{Context, Poll};
 use futures_sink::Sink;
 use pin_utils::{unsafe_pinned, unsafe_unpinned};
 
-/// Stream for the [`enumerate`](super::EnumerateExt::enumerate) method.
+/// Stream for the [`enumerate`](super::StreamExt::enumerate) method.
 #[derive(Debug)]
 #[must_use = "streams do nothing unless polled"]
 pub struct Enumerate<St: Stream> {

futures-util/src/stream/futures_unordered/mod.rs

@@ -158,7 +158,7 @@ impl<Fut> FuturesUnordered<Fut> {
     /// Push a future into the set.
     ///
     /// This method adds the given future to the set. This method will not
-    /// call [`poll`](Future::poll) on the submitted future. The caller must
+    /// call [`poll`](core::future::Future::poll) on the submitted future. The caller must
     /// ensure that [`FuturesUnordered::poll_next`](Stream::poll_next) is called
     /// in order to receive wake-up notifications for the given future.
     pub fn push(&mut self, future: Fut) {

futures-util/src/stream/mod.rs

@@ -1101,7 +1101,7 @@ pub trait StreamExt: Stream {
     ///
     /// This is similar to the [`next`][StreamExt::next] method, but it won't
     /// resolve to [`None`] if used on an empty [`Stream`]. Instead, the
-    /// returned future type will return [`true`] from
+    /// returned future type will return `true` from
     /// [`FusedFuture::is_terminated`][] when the [`Stream`] is empty, allowing
     /// [`select_next_some`][StreamExt::select_next_some] to be easily used with
     /// the [`select!`] macro.

futures-util/src/stream/select.rs

@@ -3,7 +3,7 @@ use core::pin::Pin;
 use futures_core::stream::{FusedStream, Stream};
 use futures_core::task::{Context, Poll};
 
-/// Stream for the [`select`] function.
+/// Stream for the [`select()`] function.
 #[derive(Debug)]
 #[must_use = "streams do nothing unless polled"]
 pub struct Select<St1, St2> {

futures-util/src/task/noop_waker.rs

@@ -17,8 +17,8 @@ fn noop_raw_waker() -> RawWaker {
 }
 
 /// Create a new [`Waker`](futures_core::task::Waker) which does
-/// nothing when `wake()` is called on it. The [`Waker`] can be converted
-/// into a [`Waker`] which will behave the same way.
+/// nothing when `wake()` is called on it. The [`Waker`](futures_core::task::Waker) can be converted
+/// into a [`Waker`](futures_core::task::Waker) which will behave the same way.
 ///
 /// # Examples
 ///
@@ -36,7 +36,7 @@ pub fn noop_waker() -> Waker {
 
 /// Get a thread local reference to a
 /// [`Waker`](futures_core::task::Waker) referencing a singleton
-/// instance of a [`Waker`] which panics when woken.
+/// instance of a [`Waker`](futures_core::task::Waker) which panics when woken.
 ///
 /// # Examples
 ///

futures-util/src/task/spawn.rs

@@ -52,8 +52,8 @@ pub trait SpawnExt: Spawn {
     /// Spawns a task that polls the given future to completion and returns a
     /// future that resolves to the spawned future's output.
     ///
-    /// This method returns a [`Result`] that contains a [`RemoteHandle`], or, if
-    /// spawning fails, a [`SpawnError`]. [`RemoteHandle`] is a future that
+    /// This method returns a [`Result`] that contains a [`RemoteHandle`](crate::future::RemoteHandle), or, if
+    /// spawning fails, a [`SpawnError`]. [`RemoteHandle`](crate::future::RemoteHandle) is a future that
     /// resolves to the output of the spawned future.
     ///
     /// ```
@@ -131,8 +131,8 @@ pub trait LocalSpawnExt: LocalSpawn {
     /// Spawns a task that polls the given future to completion and returns a
     /// future that resolves to the spawned future's output.
     ///
-    /// This method returns a [`Result`] that contains a [`RemoteHandle`], or, if
-    /// spawning fails, a [`SpawnError`]. [`RemoteHandle`] is a future that
+    /// This method returns a [`Result`] that contains a [`RemoteHandle`](crate::future::RemoteHandle), or, if
+    /// spawning fails, a [`SpawnError`]. [`RemoteHandle`](crate::future::RemoteHandle) is a future that
     /// resolves to the output of the spawned future.
     ///
     /// ```

futures-util/src/task/waker_ref.rs

@@ -6,6 +6,9 @@ use core::marker::PhantomData;
 use core::ops::Deref;
 use core::task::{Waker, RawWaker, RawWakerVTable};
 
+// TODO: The link to Waker below points to futures::task::Waker and not to std. Is that a
+// bug in rustdoc?
+//
 /// A [`Waker`](::std::task::Waker) that is only valid for a given lifetime.
 ///
 /// Note: this type implements [`Deref<Target = Waker>`](::std::ops::Deref),
@@ -42,10 +45,10 @@ impl Deref for WakerRef<'_> {
 unsafe fn noop(_data: *const ()) {}
 
 /// Creates a reference to a [`Waker`](::std::task::Waker)
-/// from a local [`wake`](::std::task::Wake).
+/// from a local [`ArcWake`].
 ///
 /// The resulting [`Waker`](::std::task::Waker) will call
-/// [`wake.wake()`](::std::task::Wake::wake) if awoken.
+/// [`ArcWake.wake()`](ArcWake::wake) if awoken.
 #[inline]
 pub fn waker_ref<W>(wake: &Arc<W>) -> WakerRef<'_>
 where

futures-util/src/try_stream/mod.rs

@@ -215,7 +215,7 @@ pub trait TryStreamExt: TryStream {
     /// Any successful values produced by this stream will not be passed to the
     /// closure, and will be passed through.
     ///
-    /// The returned value of the closure must implement the [`TryFuture`] trait
+    /// The returned value of the closure must implement the [`TryFuture`](futures_core::future::TryFuture) trait
     /// and can represent some more work to be done before the composed stream
     /// is finished.
     ///
@@ -639,7 +639,7 @@ pub trait TryStreamExt: TryStream {
 
     /// Attempt to execute several futures from a stream concurrently.
     ///
-    /// This stream's `Ok` type must be a [`TryFuture`] with an `Error` type
+    /// This stream's `Ok` type must be a [`TryFuture`](futures_core::future::TryFuture) with an `Error` type
     /// that matches the stream's `Error` type.
     ///
     /// This adaptor will buffer up to `n` futures and then return their
@@ -709,7 +709,9 @@ pub trait TryStreamExt: TryStream {
         TryBufferUnordered::new(self, n)
     }
 
-    /// A convenience method for calling [`TryStream::poll_next_unpin`] on [`Unpin`]
+    // TODO: false positive warning from rustdoc. Verify once #43466 settles
+    //
+    /// A convenience method for calling [`TryStream::try_poll_next`] on [`Unpin`]
     /// stream types.
     fn try_poll_next_unpin(
         &mut self,
@@ -748,9 +750,10 @@ pub trait TryStreamExt: TryStream {
         Compat::new(self)
     }
 
-    /// Adapter that converts this stream into an [`AsyncRead`].
+
+    /// Adapter that converts this stream into an [`AsyncRead`](crate::io::AsyncRead).
     ///
-    /// Note that because `into_async_read` moves the stream, the [`Stream`] type must be
+    /// Note that because `into_async_read` moves the stream, the [`Stream`](futures_core::stream::Stream) type must be
     /// [`Unpin`]. If you want to use `into_async_read` with a [`!Unpin`](Unpin) stream, you'll
     /// first have to pin the stream. This can be done by boxing the stream using [`Box::pin`]
     /// or pinning it to the stack using the `pin_mut!` macro from the `pin_utils` crate.