docs: improve discoverability of codec module (#2523)

10 files changed, 67 insertions, 30 deletions

diff --git a/tokio-test/src/io.rs b/tokio-test/src/io.rs
index 8af6a9f6..26ef57e4 100644
--- a/tokio-test/src/io.rs
+++ b/tokio-test/src/io.rs
@@ -12,7 +12,7 @@
 //!
 //! # Usage
 //!
-//! Attempting to write data that the mock isn't expected will result in a
+//! Attempting to write data that the mock isn't expecting will result in a
 //! panic.
 //!
 //! [`AsyncRead`]: tokio::io::AsyncRead
diff --git a/tokio-util/src/codec/mod.rs b/tokio-util/src/codec/mod.rs
index 96e9f9f9..e89aa7c9 100644
--- a/tokio-util/src/codec/mod.rs
+++ b/tokio-util/src/codec/mod.rs
@@ -1,8 +1,13 @@
-//! Utilities for encoding and decoding frames.
+//! Adaptors from AsyncRead/AsyncWrite to Stream/Sink
 //!
-//! Contains adapters to go from streams of bytes, [`AsyncRead`] and
-//! [`AsyncWrite`], to framed streams implementing [`Sink`] and [`Stream`].
-//! Framed streams are also known as transports.
+//! Raw I/O objects work with byte sequences, but higher-level code
+//! usually wants to batch these into meaningful chunks, called
+//! "frames".
+//!
+//! This module contains adapters to go from streams of bytes,
+//! [`AsyncRead`] and [`AsyncWrite`], to framed streams implementing
+//! [`Sink`] and [`Stream`].  Framed streams are also known as
+//! transports.
 //!
 //! [`AsyncRead`]: tokio::io::AsyncRead
 //! [`AsyncWrite`]: tokio::io::AsyncWrite
diff --git a/tokio/src/io/mod.rs b/tokio/src/io/mod.rs
index 29d8bc55..eddd6122 100644
--- a/tokio/src/io/mod.rs
+++ b/tokio/src/io/mod.rs
@@ -15,19 +15,19 @@
 //! type will _yield_ to the Tokio scheduler when IO is not ready, rather than
 //! blocking. This allows other tasks to run while waiting on IO.
 //!
-//! Another difference is that [`AsyncRead`] and [`AsyncWrite`] only contain
+//! Another difference is that `AsyncRead` and `AsyncWrite` only contain
 //! core methods needed to provide asynchronous reading and writing
 //! functionality. Instead, utility methods are defined in the [`AsyncReadExt`]
 //! and [`AsyncWriteExt`] extension traits. These traits are automatically
-//! implemented for all values that implement [`AsyncRead`] and [`AsyncWrite`]
+//! implemented for all values that implement `AsyncRead` and `AsyncWrite`
 //! respectively.
 //!
-//! End users will rarely interact directly with [`AsyncRead`] and
-//! [`AsyncWrite`]. Instead, they will use the async functions defined in the
-//! extension traits. Library authors are expected to implement [`AsyncRead`]
-//! and [`AsyncWrite`] in order to provide types that behave like byte streams.
+//! End users will rarely interact directly with `AsyncRead` and
+//! `AsyncWrite`. Instead, they will use the async functions defined in the
+//! extension traits. Library authors are expected to implement `AsyncRead`
+//! and `AsyncWrite` in order to provide types that behave like byte streams.
 //!
-//! Even with these differences, Tokio's [`AsyncRead`] and [`AsyncWrite`] traits
+//! Even with these differences, Tokio's `AsyncRead` and `AsyncWrite` traits
 //! can be used in almost exactly the same manner as the standard library's
 //! `Read` and `Write`. Most types in the standard library that implement `Read`
 //! and `Write` have asynchronous equivalents in `tokio` that implement
@@ -122,12 +122,26 @@
 //!
 //! ## Implementing AsyncRead and AsyncWrite
 //!
-//! Because they are traits, we can implement `AsyncRead` and `AsyncWrite` for
+//! Because they are traits, we can implement [`AsyncRead`] and [`AsyncWrite`] for
 //! our own types, as well. Note that these traits must only be implemented for
 //! non-blocking I/O types that integrate with the futures type system. In
 //! other words, these types must never block the thread, and instead the
 //! current task is notified when the I/O resource is ready.
 //!
+//! ## Conversion to and from Sink/Stream
+//!
+//! It is often convenient to encapsulate the reading and writing of
+//! bytes and instead work with a [`Sink`] or [`Stream`] of some data
+//! type that is encoded as bytes and/or decoded from bytes. Tokio
+//! provides some utility traits in the [tokio-util] crate that
+//! abstract the asynchronous buffering that is required and allows
+//! you to write [`Encoder`] and [`Decoder`] functions working with a
+//! buffer of bytes, and then use that ["codec"] to transform anything
+//! that implements [`AsyncRead`] and [`AsyncWrite`] into a `Sink`/`Stream` of
+//! your structured data.
+//!
+//! [tokio-util]: https://docs.rs/tokio-util/0.3/tokio_util/codec/index.html
+//!
 //! # Standard input and output
 //!
 //! Tokio provides asynchronous APIs to standard [input], [output], and [error].
@@ -149,10 +163,17 @@
 //!
 //! [`AsyncRead`]: trait@AsyncRead
 //! [`AsyncWrite`]: trait@AsyncWrite
+//! [`AsyncReadExt`]: trait@AsyncReadExt
+//! [`AsyncWriteExt`]: trait@AsyncWriteExt
+//! ["codec"]: https://docs.rs/tokio-util/0.3/tokio_util/codec/index.html
+//! [`Encoder`]: https://docs.rs/tokio-util/0.3/tokio_util/codec/trait.Encoder.html
+//! [`Decoder`]: https://docs.rs/tokio-util/0.3/tokio_util/codec/trait.Decoder.html
 //! [`Error`]: struct@Error
 //! [`ErrorKind`]: enum@ErrorKind
 //! [`Result`]: type@Result
 //! [`Read`]: std::io::Read
+//! [`Sink`]: https://docs.rs/futures/0.3/futures/sink/trait.Sink.html
+//! [`Stream`]: crate::stream::Stream
 //! [`Write`]: std::io::Write
 cfg_io_blocking! {
     pub(crate) mod blocking;
diff --git a/tokio/src/process/mod.rs b/tokio/src/process/mod.rs
index 72315112..ab3dae18 100644
--- a/tokio/src/process/mod.rs
+++ b/tokio/src/process/mod.rs
@@ -6,6 +6,8 @@
 //! variants) return "future aware" types that interoperate with Tokio. The asynchronous process
 //! support is provided through signal handling on Unix and system APIs on Windows.
 //!
+//! [`std::process::Command`]: std::process::Command
+//!
 //! # Examples
 //!
 //! Here's an example program which will spawn `echo hello world` and then wait
@@ -140,6 +142,9 @@ use std::task::Poll;
 /// [output](Command::output).
 ///
 /// `Command` uses asynchronous versions of some `std` types (for example [`Child`]).
+///
+/// [`std::process::Command`]: std::process::Command
+/// [`Child`]: struct@Child
 #[derive(Debug)]
 pub struct Command {
     std: StdCommand,
@@ -171,7 +176,7 @@ impl Command {
     /// The search path to be used may be controlled by setting the
     /// `PATH` environment variable on the Command,
     /// but this has some implementation limitations on Windows
-    /// (see issue rust-lang/rust#37519).
+    /// (see issue [rust-lang/rust#37519]).
     ///
     /// # Examples
     ///
@@ -181,6 +186,8 @@ impl Command {
     /// use tokio::process::Command;
     /// let command = Command::new("sh");
     /// ```
+    ///
+    /// [rust-lang/rust#37519]: https://github.com/rust-lang/rust/issues/37519
     pub fn new<S: AsRef<OsStr>>(program: S) -> Command {
         Self::from(StdCommand::new(program))
     }
diff --git a/tokio/src/stream/empty.rs b/tokio/src/stream/empty.rs
index 6118673e..2f56ac6c 100644
--- a/tokio/src/stream/empty.rs
+++ b/tokio/src/stream/empty.rs
@@ -4,7 +4,7 @@ use core::marker::PhantomData;
 use core::pin::Pin;
 use core::task::{Context, Poll};
 
-/// Stream for the [`empty`] function.
+/// Stream for the [`empty`](fn@empty) function.
 #[derive(Debug)]
 #[must_use = "streams do nothing unless polled"]
 pub struct Empty<T>(PhantomData<T>);
diff --git a/tokio/src/stream/iter.rs b/tokio/src/stream/iter.rs
index 36eeb561..d84929d7 100644
--- a/tokio/src/stream/iter.rs
+++ b/tokio/src/stream/iter.rs
@@ -3,7 +3,7 @@ use crate::stream::Stream;
 use core::pin::Pin;
 use core::task::{Context, Poll};
 
-/// Stream for the [`iter`] function.
+/// Stream for the [`iter`](fn@iter) function.
 #[derive(Debug)]
 #[must_use = "streams do nothing unless polled"]
 pub struct Iter<I> {
diff --git a/tokio/src/stream/once.rs b/tokio/src/stream/once.rs
index 04a642f3..7fe204cc 100644
--- a/tokio/src/stream/once.rs
+++ b/tokio/src/stream/once.rs
@@ -4,7 +4,7 @@ use core::option;
 use core::pin::Pin;
 use core::task::{Context, Poll};
 
-/// Stream for the [`once`] function.
+/// Stream for the [`once`](fn@once) function.
 #[derive(Debug)]
 #[must_use = "streams do nothing unless polled"]
 pub struct Once<T> {
diff --git a/tokio/src/stream/pending.rs b/tokio/src/stream/pending.rs
index 2e06a1c2..21224c38 100644
--- a/tokio/src/stream/pending.rs
+++ b/tokio/src/stream/pending.rs
@@ -4,7 +4,7 @@ use core::marker::PhantomData;
 use core::pin::Pin;
 use core::task::{Context, Poll};
 
-/// Stream for the [`pending`] function.
+/// Stream for the [`pending`](fn@pending) function.
 #[derive(Debug)]
 #[must_use = "streams do nothing unless polled"]
 pub struct Pending<T>(PhantomData<T>);
diff --git a/tokio/src/sync/mod.rs b/tokio/src/sync/mod.rs
index 933e903a..3d96106d 100644
--- a/tokio/src/sync/mod.rs
+++ b/tokio/src/sync/mod.rs
@@ -58,11 +58,12 @@
 //! }
 //! ```
 //!
-//! Note, if the task produces the the computation result as its final action
-//! before terminating, the [`JoinHandle`] can be used to receive the
-//! computation result instead of allocating resources for the `oneshot`
-//! channel. Awaiting on [`JoinHandle`] returns `Result`. If the task panics,
-//! the `Joinhandle` yields `Err` with the panic cause.
+//! Note, if the task produces a computation result as its final
+//! action before terminating, the [`JoinHandle`] can be used to
+//! receive that value instead of allocating resources for the
+//! `oneshot` channel. Awaiting on [`JoinHandle`] returns `Result`. If
+//! the task panics, the `Joinhandle` yields `Err` with the panic
+//! cause.
 //!
 //! **Example:**
 //!
@@ -84,6 +85,7 @@
 //! }
 //! ```
 //!
+//! [oneshot]: oneshot
 //! [`JoinHandle`]: crate::task::JoinHandle
 //!
 //! ## `mpsc` channel
@@ -230,6 +232,8 @@
 //! }
 //! ```
 //!
+//! [mpsc]: mpsc
+//!
 //! ## `broadcast` channel
 //!
 //! The [`broadcast` channel] supports sending **many** values from
@@ -405,23 +409,23 @@
 //! operate in a similar way as their `std` counterparts parts but will wait
 //! asynchronously instead of blocking the thread.
 //!
-//! * [`Barrier`][Barrier] Ensures multiple tasks will wait for each other to
+//! * [`Barrier`](Barrier) Ensures multiple tasks will wait for each other to
 //!   reach a point in the program, before continuing execution all together.
 //!
-//! * [`Mutex`][Mutex] Mutual Exclusion mechanism, which ensures that at most
+//! * [`Mutex`](Mutex) Mutual Exclusion mechanism, which ensures that at most
 //!   one thread at a time is able to access some data.
 //!
-//! * [`Notify`][Notify] Basic task notification. `Notify` supports notifying a
+//! * [`Notify`](Notify) Basic task notification. `Notify` supports notifying a
 //!   receiving task without sending data. In this case, the task wakes up and
 //!   resumes processing.
 //!
-//! * [`RwLock`][RwLock] Provides a mutual exclusion mechanism which allows
+//! * [`RwLock`](RwLock) Provides a mutual exclusion mechanism which allows
 //!   multiple readers at the same time, while allowing only one writer at a
 //!   time. In some cases, this can be more efficient than a mutex.
 //!
-//! * [`Semaphore`][Semaphore] Limits the amount of concurrency. A semaphore
+//! * [`Semaphore`](Semaphore) Limits the amount of concurrency. A semaphore
 //!   holds a number of permits, which tasks may request in order to enter a
-//!   critical section. Semaphores are useful for implementing limiting of
+//!   critical section. Semaphores are useful for implementing limiting or
 //!   bounding of any kind.
 
 cfg_sync! {
diff --git a/tokio/src/sync/semaphore_ll.rs b/tokio/src/sync/semaphore_ll.rs
index 0bdc4e27..ac4ae6fa 100644
--- a/tokio/src/sync/semaphore_ll.rs
+++ b/tokio/src/sync/semaphore_ll.rs
@@ -749,7 +749,7 @@ impl Permit {
     /// Forgets the permit **without** releasing it back to the semaphore.
     ///
     /// After calling `forget`, `poll_acquire` is able to acquire new permit
-    /// from the sempahore.
+    /// from the semaphore.
     ///
     /// Repeatedly calling `forget` without associated calls to `add_permit`
     /// will result in the semaphore losing all permits.