Update doc comments (#2572)

* Update doc comments

* Remove trailing whitespace

7 files changed, 26 insertions, 18 deletions

diff --git a/tokio/src/future/ready.rs b/tokio/src/future/ready.rs
index d74f999e..de2d60c1 100644
--- a/tokio/src/future/ready.rs
+++ b/tokio/src/future/ready.rs
@@ -2,7 +2,7 @@ use std::future::Future;
 use std::pin::Pin;
 use std::task::{Context, Poll};
 
-/// Future for the [`ready`](ready()) function.
+/// Future for the [`ok`](ok()) function.
 ///
 /// `pub` in order to use the future as an associated type in a sealed trait.
 #[derive(Debug)]
diff --git a/tokio/src/io/util/flush.rs b/tokio/src/io/util/flush.rs
index 1465f304..534a5160 100644
--- a/tokio/src/io/util/flush.rs
+++ b/tokio/src/io/util/flush.rs
@@ -8,7 +8,8 @@ use std::task::{Context, Poll};
 cfg_io_util! {
     /// A future used to fully flush an I/O object.
     ///
-    /// Created by the [`AsyncWriteExt::flush`] function.
+    /// Created by the [`AsyncWriteExt::flush`][flush] function.
+    /// [flush]: crate::io::AsyncWriteExt::flush
     #[derive(Debug)]
     pub struct Flush<'a, A: ?Sized> {
         a: &'a mut A,
diff --git a/tokio/src/io/util/read_buf.rs b/tokio/src/io/util/read_buf.rs
index 97e670de..6ee3d249 100644
--- a/tokio/src/io/util/read_buf.rs
+++ b/tokio/src/io/util/read_buf.rs
@@ -15,7 +15,7 @@ where
 }
 
 cfg_io_util! {
-    /// Future returned by [`read_buf`](AsyncReadExt::read_buf).
+    /// Future returned by [`read_buf`](crate::io::AsyncReadExt::read_buf).
     #[derive(Debug)]
     #[must_use = "futures do nothing unless you `.await` or poll them"]
     pub struct ReadBuf<'a, R, B> {
diff --git a/tokio/src/io/util/read_exact.rs b/tokio/src/io/util/read_exact.rs
index d6983c99..86b84129 100644
--- a/tokio/src/io/util/read_exact.rs
+++ b/tokio/src/io/util/read_exact.rs
@@ -9,7 +9,8 @@ use std::task::{Context, Poll};
 /// A future which can be used to easily read exactly enough bytes to fill
 /// a buffer.
 ///
-/// Created by the [`AsyncRead::read_exact`].
+/// Created by the [`AsyncReadExt::read_exact`][read_exact].
+/// [read_exact]: [crate::io::AsyncReadExt::read_exact]
 pub(crate) fn read_exact<'a, A>(reader: &'a mut A, buf: &'a mut [u8]) -> ReadExact<'a, A>
 where
     A: AsyncRead + Unpin + ?Sized,
diff --git a/tokio/src/io/util/shutdown.rs b/tokio/src/io/util/shutdown.rs
index f24e2885..33ac0ac0 100644
--- a/tokio/src/io/util/shutdown.rs
+++ b/tokio/src/io/util/shutdown.rs
@@ -8,7 +8,8 @@ use std::task::{Context, Poll};
 cfg_io_util! {
     /// A future used to shutdown an I/O object.
     ///
-    /// Created by the [`AsyncWriteExt::shutdown`] function.
+    /// Created by the [`AsyncWriteExt::shutdown`][shutdown] function.
+    /// [shutdown]: crate::io::AsyncWriteExt::shutdown
     #[derive(Debug)]
     pub struct Shutdown<'a, A: ?Sized> {
         a: &'a mut A,
diff --git a/tokio/src/runtime/context.rs b/tokio/src/runtime/context.rs
index 4af2df23..1b267f48 100644
--- a/tokio/src/runtime/context.rs
+++ b/tokio/src/runtime/context.rs
@@ -47,9 +47,9 @@ cfg_rt_core! {
     }
 }
 
-/// Set this [`ThreadContext`] as the current active [`ThreadContext`].
+/// Set this [`Handle`] as the current active [`Handle`].
 ///
-/// [`ThreadContext`]: struct@ThreadContext
+/// [`Handle`]: Handle
 pub(crate) fn enter<F, R>(new: Handle, f: F) -> R
 where
     F: FnOnce() -> R,
diff --git a/tokio/src/time/driver/mod.rs b/tokio/src/time/driver/mod.rs
index 4616816f..554042fc 100644
--- a/tokio/src/time/driver/mod.rs
+++ b/tokio/src/time/driver/mod.rs
@@ -26,29 +26,29 @@ use std::sync::Arc;
 use std::usize;
 use std::{cmp, fmt};
 
-/// Time implementation that drives [`Delay`], [`Interval`], and [`Timeout`].
+/// Time implementation that drives [`Delay`][delay], [`Interval`][interval], and [`Timeout`][timeout].
 ///
 /// A `Driver` instance tracks the state necessary for managing time and
-/// notifying the [`Delay`] instances once their deadlines are reached.
+/// notifying the [`Delay`][delay] instances once their deadlines are reached.
 ///
-/// It is expected that a single instance manages many individual [`Delay`]
+/// It is expected that a single instance manages many individual [`Delay`][delay]
 /// instances. The `Driver` implementation is thread-safe and, as such, is able
 /// to handle callers from across threads.
 ///
-/// After creating the `Driver` instance, the caller must repeatedly call
-/// [`turn`]. The time driver will perform no work unless [`turn`] is called
-/// repeatedly.
+/// After creating the `Driver` instance, the caller must repeatedly call `park`
+/// or `park_timeout`. The time driver will perform no work unless `park` or
+/// `park_timeout` is called repeatedly.
 ///
 /// The driver has a resolution of one millisecond. Any unit of time that falls
 /// between milliseconds are rounded up to the next millisecond.
 ///
-/// When an instance is dropped, any outstanding [`Delay`] instance that has not
+/// When an instance is dropped, any outstanding [`Delay`][delay] instance that has not
 /// elapsed will be notified with an error. At this point, calling `poll` on the
-/// [`Delay`] instance will result in `Err` being returned.
+/// [`Delay`][delay] instance will result in panic.
 ///
 /// # Implementation
 ///
-/// THe time driver is based on the [paper by Varghese and Lauck][paper].
+/// The time driver is based on the [paper by Varghese and Lauck][paper].
 ///
 /// A hashed timing wheel is a vector of slots, where each slot handles a time
 /// slice. As time progresses, the timer walks over the slot for the current
@@ -73,9 +73,14 @@ use std::{cmp, fmt};
 /// When the timer processes entries at level zero, it will notify all the
 /// `Delay` instances as their deadlines have been reached. For all higher
 /// levels, all entries will be redistributed across the wheel at the next level
-/// down. Eventually, as time progresses, entries will [`Delay`] instances will
+/// down. Eventually, as time progresses, entries will [`Delay`][delay] instances will
 /// either be canceled (dropped) or their associated entries will reach level
 /// zero and be notified.
+///
+/// [paper]: http://www.cs.columbia.edu/~nahum/w6998/papers/ton97-timing-wheels.pdf
+/// [delay]: crate::time::Delay
+/// [timeout]: crate::time::Timeout
+/// [interval]: crate::time::Interval
 #[derive(Debug)]
 pub(crate) struct Driver<T> {
     /// Shared state
@@ -119,7 +124,7 @@ where
     T: Park,
 {
     /// Creates a new `Driver` instance that uses `park` to block the current
-    /// thread and `now` to get the current `Instant`.
+    /// thread and `clock` to get the current `Instant`.
     ///
     /// Specifying the source of time is useful when testing.
     pub(crate) fn new(park: T, clock: Clock) -> Driver<T> {