Rollup merge of #65554 - gliderkite:bufreader-doc-enhance, r=KodrAus

Enhance the documentation of BufReader for potential data loss

This is (IMO) and enhancement of the `std::io::BufReader` documentation, that aims to highlight how relatively easy is to end up with data loss when improperly using an instance of this class.

This is following the issue I had figuring out why my application was loosing data, because I focused my attention on the word *multiple instances* of `BufReader` in its `struct` documentation, even if I ever only had one instance.

Link to the issue: https://github.com/tokio-rs/tokio/issues/1662

1 files changed, 5 insertions, 2 deletions

diff --git a/src/libstd/io/buffered.rs b/src/libstd/io/buffered.rs
index 9593a1bae0a..ad567c97c2c 100644
--- a/src/libstd/io/buffered.rs
+++ b/src/libstd/io/buffered.rs
@@ -24,7 +24,9 @@ use crate::memchr;
 ///
 /// When the `BufReader<R>` is dropped, the contents of its buffer will be
 /// discarded. Creating multiple instances of a `BufReader<R>` on the same
-/// stream can cause data loss.
+/// stream can cause data loss. Reading from the underlying reader after
+/// unwrapping the `BufReader<R>` with `BufReader::into_inner` can also cause
+/// data loss.
 ///
 /// [`Read`]: ../../std/io/trait.Read.html
 /// [`TcpStream::read`]: ../../std/net/struct.TcpStream.html#method.read
@@ -179,7 +181,8 @@ impl<R> BufReader<R> {
 
     /// Unwraps this `BufReader<R>`, returning the underlying reader.
     ///
-    /// Note that any leftover data in the internal buffer is lost.
+    /// Note that any leftover data in the internal buffer is lost. Therefore,
+    /// a following read from the underlying reader may lead to data loss.
     ///
     /// # Examples
     ///