docs: improve tokio::io API documentation (#2060)

* Links are added where missing and examples are improved.
* Improve `stdin`, `stdout`, and `stderr` documentation by going
  into more details regarding what can go wrong in concurrent
  situations and provide examples for `stdout` and `stderr`.

5 files changed, 46 insertions, 33 deletions

diff --git a/tokio/src/io/util/async_buf_read_ext.rs b/tokio/src/io/util/async_buf_read_ext.rs
index b2930652..90789744 100644
--- a/tokio/src/io/util/async_buf_read_ext.rs
+++ b/tokio/src/io/util/async_buf_read_ext.rs
@@ -5,7 +5,9 @@ use crate::io::util::split::{split, Split};
 use crate::io::AsyncBufRead;
 
 cfg_io_util! {
-    /// An extension trait which adds utility methods to `AsyncBufRead` types.
+    /// An extension trait which adds utility methods to [`AsyncBufRead`] types.
+    ///
+    /// [`AsyncBufRead`]: crate::io::AsyncBufRead
     pub trait AsyncBufReadExt: AsyncBufRead {
         /// Read all bytes into `buf` until the delimiter `byte` or EOF is reached.
         ///
diff --git a/tokio/src/io/util/copy.rs b/tokio/src/io/util/copy.rs
index 0a2aea73..8e0058c1 100644
--- a/tokio/src/io/util/copy.rs
+++ b/tokio/src/io/util/copy.rs
@@ -36,6 +36,8 @@ cfg_io_util! {
     ///
     /// This is an asynchronous version of [`std::io::copy`][std].
     ///
+    /// [std]: std::io::copy
+    ///
     /// # Errors
     ///
     /// The returned future will finish with an error will return an error
@@ -56,8 +58,6 @@ cfg_io_util! {
     /// # Ok(())
     /// # }
     /// ```
-    ///
-    /// [std]: std::io::copy
     pub fn copy<'a, R, W>(reader: &'a mut R, writer: &'a mut W) -> Copy<'a, R, W>
     where
         R: AsyncRead + Unpin + ?Sized,
diff --git a/tokio/src/io/util/empty.rs b/tokio/src/io/util/empty.rs
index 054d8e60..7075612f 100644
--- a/tokio/src/io/util/empty.rs
+++ b/tokio/src/io/util/empty.rs
@@ -6,7 +6,7 @@ use std::pin::Pin;
 use std::task::{Context, Poll};
 
 cfg_io_util! {
-    // An async reader which is always at EOF.
+    /// An async reader which is always at EOF.
     ///
     /// This struct is generally created by calling [`empty`]. Please see
     /// the documentation of [`empty()`][`empty`] for more details.
@@ -14,7 +14,7 @@ cfg_io_util! {
     /// This is an asynchronous version of [`std::io::empty`][std].
     ///
     /// [`empty`]: fn.empty.html
-    /// [std]: https://doc.rust-lang.org/std/io/struct.Empty.html
+    /// [std]: std::io::empty
     pub struct Empty {
         _p: (),
     }
@@ -25,20 +25,22 @@ cfg_io_util! {
     ///
     /// This is an asynchronous version of [`std::io::empty`][std].
     ///
+    /// [std]: std::io::empty
+    ///
     /// # Examples
     ///
     /// A slightly sad example of not reading anything into a buffer:
     ///
-    /// ```rust
-    /// # use tokio::io::{self, AsyncReadExt};
-    /// # async fn dox() {
-    /// let mut buffer = String::new();
-    /// io::empty().read_to_string(&mut buffer).await.unwrap();
-    /// assert!(buffer.is_empty());
-    /// # }
     /// ```
+    /// use tokio::io::{self, AsyncReadExt};
     ///
-    /// [std]: https://doc.rust-lang.org/std/io/fn.empty.html
+    /// #[tokio::main]
+    /// async fn main() {
+    ///     let mut buffer = String::new();
+    ///     io::empty().read_to_string(&mut buffer).await.unwrap();
+    ///     assert!(buffer.is_empty());
+    /// }
+    /// ```
     pub fn empty() -> Empty {
         Empty { _p: () }
     }
diff --git a/tokio/src/io/util/repeat.rs b/tokio/src/io/util/repeat.rs
index a74a153b..064775ee 100644
--- a/tokio/src/io/util/repeat.rs
+++ b/tokio/src/io/util/repeat.rs
@@ -14,7 +14,7 @@ cfg_io_util! {
     /// This is an asynchronous version of [`std::io::Repeat`][std].
     ///
     /// [repeat]: fn.repeat.html
-    /// [std]: https://doc.rust-lang.org/std/io/struct.Repeat.html
+    /// [std]: std::io::Repeat
     #[derive(Debug)]
     pub struct Repeat {
         byte: u8,
@@ -27,18 +27,20 @@ cfg_io_util! {
     ///
     /// This is an asynchronous version of [`std::io::repeat`][std].
     ///
+    /// [std]: std::io::repeat
+    ///
     /// # Examples
     ///
     /// ```
-    /// # use tokio::io::{self, AsyncReadExt};
-    /// # async fn dox() {
-    /// let mut buffer = [0; 3];
-    /// io::repeat(0b101).read_exact(&mut buffer).await.unwrap();
-    /// assert_eq!(buffer, [0b101, 0b101, 0b101]);
-    /// # }
-    /// ```
+    /// use tokio::io::{self, AsyncReadExt};
     ///
-    /// [std]: https://doc.rust-lang.org/std/io/fn.repeat.html
+    /// #[tokio::main]
+    /// async fn main() {
+    ///     let mut buffer = [0; 3];
+    ///     io::repeat(0b101).read_exact(&mut buffer).await.unwrap();
+    ///     assert_eq!(buffer, [0b101, 0b101, 0b101]);
+    /// }
+    /// ```
     pub fn repeat(byte: u8) -> Repeat {
         Repeat { byte }
     }
diff --git a/tokio/src/io/util/sink.rs b/tokio/src/io/util/sink.rs
index 74802f97..05ee773f 100644
--- a/tokio/src/io/util/sink.rs
+++ b/tokio/src/io/util/sink.rs
@@ -11,9 +11,10 @@ cfg_io_util! {
     /// This struct is generally created by calling [`sink`][sink]. Please
     /// see the documentation of `sink()` for more details.
     ///
-    /// This is an asynchronous version of `std::io::Sink`.
+    /// This is an asynchronous version of [`std::io::Sink`][std].
     ///
-    /// [sink]: fn.sink.html
+    /// [sink]: sink()
+    /// [std]: std::io::Sink
     pub struct Sink {
         _p: (),
     }
@@ -21,21 +22,27 @@ cfg_io_util! {
     /// Creates an instance of an async writer which will successfully consume all
     /// data.
     ///
-    /// All calls to `poll_write` on the returned instance will return
+    /// All calls to [`poll_write`] on the returned instance will return
     /// `Poll::Ready(Ok(buf.len()))` and the contents of the buffer will not be
     /// inspected.
     ///
-    /// This is an asynchronous version of `std::io::sink`.
+    /// This is an asynchronous version of [`std::io::sink`][std].
+    ///
+    /// [`poll_write`]: crate::io::AsyncWrite::poll_write()
+    /// [std]: std::io::sink
     ///
     /// # Examples
     ///
-    /// ```rust
-    /// # use tokio::io::{self, AsyncWriteExt};
-    /// # async fn dox() {
-    /// let buffer = vec![1, 2, 3, 5, 8];
-    /// let num_bytes = io::sink().write(&buffer).await.unwrap();
-    /// assert_eq!(num_bytes, 5);
-    /// # }
+    /// ```
+    /// use tokio::io::{self, AsyncWriteExt};
+    ///
+    /// #[tokio::main]
+    /// async fn main() -> io::Result<()> {
+    ///     let buffer = vec![1, 2, 3, 5, 8];
+    ///     let num_bytes = io::sink().write(&buffer).await?;
+    ///     assert_eq!(num_bytes, 5);
+    ///     Ok(())
+    /// }
     /// ```
     pub fn sink() -> Sink {
         Sink { _p: () }