Attempt to fix all documentation warnings from rustdoc.

I attempted to fix all documentation warnings in futures-rs. All of these refer to failing cross-
references. Note that it's hard to verify as there is still alot of warnings from dependencies
like rand and from what I suspect to be std, but it's unclear, since rustdoc doesn't mark the
origin of the warnings. See: rust-lang/rust#59367 and rust-lang/rust#55907

The fixes here contain several TODO's, for two main reasons:
- false positive warnings from rustdoc, where rustdoc generates a correct link but still issues
  a warning
- places where I have been obliged to put a link to an html file because I didn't manage to make
  rustdoc generate a correct link from a path.

It would be nice if people verified that commits don't throw warnings before merging,
even in rustdoc. Especially so because rustdoc does not hide warnings in dependencies
right now, even when called with `--no-deps`. That means that any warnings thrown by
futures-rs will bother every single dev that has a (indirect) dependency on futures-rs
and runs rustdoc.

Author: najamelan

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,11 @@ use futures_core::task::{Context, Poll};
 use std::io;
 use std::pin::Pin;
 
-/// Future for the [`seek`](super::SeekExt::seek) method.
+// TODO: Currently this throws a warning, but it's a false positive as it generates a
+// correct link. See: https://github.com/rust-lang/rust/issues/55907
+// Verify everything works fine here when that get's resolved.
+//
+/// Future for the [`seek`](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,9 @@ 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.
+// TODO: rustdoc false positive warning about being unable to resolve: StreamExt::enumerate
+//
+/// Stream for the [`enumerate`](StreamExt::enumerate) method.
 #[derive(Debug)]
 #[must_use = "streams do nothing unless polled"]
 pub struct Enumerate<St: Stream> {

futures-util/src/stream/mod.rs

@@ -1100,7 +1100,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/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

@@ -678,7 +678,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 [`poll_next_unpin`](StreamExt::poll_next_unpin) on [`Unpin`]
     /// stream types.
     fn try_poll_next_unpin(
         &mut self,
@@ -717,9 +719,13 @@ pub trait TryStreamExt: TryStream {
         Compat::new(self)
     }
 
-    /// Adapter that converts this stream into an [`AsyncRead`].
+    // TODO: I tried to make these doc links work, but failed to have the link work with
+    // anything other than `trait.AsyncRead.html`. We should probably try again to use
+    // paths once rustdoc has less issues.
+    //
+    /// Adapter that converts this stream into an [`AsyncRead`](trait.AsyncRead.html).
     ///
-    /// 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`](trait.Stream.html) 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.