added docs +doctests to BufRead::Consume

Author: feefladder

src/buf/reader.rs

@@ -75,6 +75,26 @@ impl<B: Buf + Sized> io::BufRead for Reader<B> {
     fn fill_buf(&mut self) -> io::Result<&[u8]> {
         Ok(self.buf.chunk())
     }
+    /// consume `amt` bytes from the buffer. 
+    /// 
+    /// Calls [`Buf::advance`] internally and will therefore not lead to a logic error.
+    /// 
+    /// # Examples
+    /// ```rust
+    /// use bytes::Buf;
+    /// use std::io::{Read, BufRead};
+    ///
+    /// let mut buf = b"hello world".reader();
+    /// let mut dst = vec![];
+    ///
+    /// // skip b"hello "
+    /// buf.consume(6);
+    /// // read b"world"
+    /// buf.read_to_end(&mut dst).unwrap();
+    /// 
+    /// assert_eq!(dst, b"world");
+    /// ```
+    /// 
     fn consume(&mut self, amt: usize) {
         self.buf.advance(amt)
     }