doc: improve AsyncBufReadExt API documentation (#1868)

Remove "old" docs that were left over during a rewrite, add examples and
additional details.

tokio/src/io/util/async_buf_read_ext.rs

@@ -7,19 +7,75 @@ use crate::io::AsyncBufRead;
 cfg_io_util! {
     /// An extension trait which adds utility methods to `AsyncBufRead` types.
     pub trait AsyncBufReadExt: AsyncBufRead {
-        /// Creates a future which will read all the bytes associated with this I/O
+        /// Read all bytes into `buf` until the delimiter `byte` or EOF is reached.
-        /// object into `buf` until the delimiter `byte` or EOF is reached.
+        ///
-        /// This method is the async equivalent to [`BufRead::read_until`](std::io::BufRead::read_until).
+        /// Equivalent to:
+        ///
+        /// ```ignore
+        /// async fn read_until(&mut self, buf: &mut Vec<u8>) -> io::Result<usize>;
+        /// ```
         ///
         /// This function will read bytes from the underlying stream until the
         /// delimiter or EOF is found. Once found, all bytes up to, and including,
         /// the delimiter (if found) will be appended to `buf`.
         ///
-        /// The returned future will resolve to the number of bytes read once the read
+        /// If successful, this function will return the total number of bytes read.
-        /// operation is completed.
         ///
-        /// In the case of an error the buffer and the object will be discarded, with
+        /// # Errors
-        /// the error yielded.
+        ///
+        /// This function will ignore all instances of [`ErrorKind::Interrupted`] and
+        /// will otherwise return any errors returned by [`fill_buf`].
+        ///
+        /// If an I/O error is encountered then all bytes read so far will be
+        /// present in `buf` and its length will have been adjusted appropriately.
+        ///
+        /// [`fill_buf`]: AsyncBufRead::poll_fill_buf
+        /// [`ErrorKind::Interrupted`]: std::io::ErrorKind::Interrupted
+        ///
+        /// # Examples
+        ///
+        /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In
+        /// this example, we use [`Cursor`] to read all the bytes in a byte slice
+        /// in hyphen delimited segments:
+        ///
+        /// [`Cursor`]: std::io::Cursor
+        ///
+        /// ```
+        /// use tokio::io::AsyncBufReadExt;
+        ///
+        /// use std::io::Cursor;
+        ///
+        /// #[tokio::main]
+        /// async fn main() {
+        ///     let mut cursor = Cursor::new(b"lorem-ipsum");
+        ///     let mut buf = vec![];
+        ///
+        ///     // cursor is at 'l'
+        ///     let num_bytes = cursor.read_until(b'-', &mut buf)
+        ///         .await
+        ///         .expect("reading from cursor won't fail");
+        ///
+        ///     assert_eq!(num_bytes, 6);
+        ///     assert_eq!(buf, b"lorem-");
+        ///     buf.clear();
+        ///
+        ///     // cursor is at 'i'
+        ///     let num_bytes = cursor.read_until(b'-', &mut buf)
+        ///         .await
+        ///         .expect("reading from cursor won't fail");
+        ///
+        ///     assert_eq!(num_bytes, 5);
+        ///     assert_eq!(buf, b"ipsum");
+        ///     buf.clear();
+        ///
+        ///     // cursor is at EOF
+        ///     let num_bytes = cursor.read_until(b'-', &mut buf)
+        ///         .await
+        ///         .expect("reading from cursor won't fail");
+        ///     assert_eq!(num_bytes, 0);
+        ///     assert_eq!(buf, b"");
+        /// }
+        /// ```
         fn read_until<'a>(&'a mut self, byte: u8, buf: &'a mut Vec<u8>) -> ReadUntil<'a, Self>
         where
             Self: Unpin,
@@ -27,33 +83,15 @@ cfg_io_util! {
             read_until(self, byte, buf)
         }
 
-        /// Creates a future which will read all the bytes associated with this I/O
-        /// object into `buf` until a newline (the 0xA byte) or EOF is reached,
-        /// This method is the async equivalent to [`BufRead::read_line`](std::io::BufRead::read_line).
-        ///
-        /// This function will read bytes from the underlying stream until the
-        /// newline delimiter (the 0xA byte) or EOF is found. Once found, all bytes
-        /// up to, and including, the delimiter (if found) will be appended to
-        /// `buf`.
-        ///
-        /// The returned future will resolve to the number of bytes read once the read
-        /// operation is completed.
-        ///
-        /// In the case of an error the buffer and the object will be discarded, with
-        /// the error yielded.
-        ///
-        /// # Errors
-        ///
-        /// This function has the same error semantics as [`read_until`] and will
-        /// also return an error if the read bytes are not valid UTF-8. If an I/O
-        /// error is encountered then `buf` may contain some bytes already read in
-        /// the event that all data read so far was valid UTF-8.
-        ///
-        /// [`read_until`]: AsyncBufReadExt::read_until
-        /// ------------
         /// Read all bytes until a newline (the 0xA byte) is reached, and append
         /// them to the provided buffer.
         ///
+        /// Equivalent to:
+        ///
+        /// ```ignore
+        /// async fn read_line(&mut self, buf: &mut String) -> io::Result<usize>;
+        /// ```
+        ///
         /// This function will read bytes from the underlying stream until the
         /// newline delimiter (the 0xA byte) or EOF is found. Once found, all bytes
         /// up to, and including, the delimiter (if found) will be appended to
@@ -178,6 +216,33 @@ cfg_io_util! {
         ///
         /// Each line of the stream has the same error semantics as [`AsyncBufReadExt::read_line`].
         ///
+        /// # Examples
+        ///
+        /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In
+        /// this example, we use [`Cursor`] to iterate over all the lines in a byte
+        /// slice.
+        ///
+        /// [`Cursor`]: std::io::Cursor
+        ///
+        /// ```
+        /// use tokio::io::AsyncBufReadExt;
+        ///
+        /// use futures::{StreamExt};
+        /// use std::io::Cursor;
+        ///
+        /// #[tokio::main]
+        /// async fn main() {
+        ///     let cursor = Cursor::new(b"lorem\nipsum\r\ndolor");
+        ///
+        ///     let mut lines = cursor.lines().map(|res| res.unwrap());
+        ///
+        ///     assert_eq!(lines.next().await, Some(String::from("lorem")));
+        ///     assert_eq!(lines.next().await, Some(String::from("ipsum")));
+        ///     assert_eq!(lines.next().await, Some(String::from("dolor")));
+        ///     assert_eq!(lines.next().await, None);
+        /// }
+        /// ```
+        ///
         /// [`AsyncBufReadExt::read_line`]: AsyncBufReadExt::read_line
         fn lines(self) -> Lines<Self>
         where