From 0f30ab8c0a67707e57ac238e7e6b42821b05ba8a Mon Sep 17 00:00:00 2001
From: boats <boats@mozilla.com>
Date: Tue, 26 Nov 2019 14:23:10 +0100
Subject: [PATCH] Fix the docs and Debug output of BufWriter. (#588)

The BufWriter docs inaccurately stated that it flushes on drop, which it does
not do. This PR changes the docs, as well as the example, to highlight that
the user must explicitly flush a bufwriter.

There were also two places where the BufWriter code referred to it as a
BufReader: in the link to the std docs, and in the Debug output. Those have
also been fixed.
---
 src/io/buf_writer.rs | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/src/io/buf_writer.rs b/src/io/buf_writer.rs
index ce6a97b..c527d02 100644
--- a/src/io/buf_writer.rs
+++ b/src/io/buf_writer.rs
@@ -22,14 +22,14 @@ pin_project! {
     /// times. It also provides no advantage when writing to a destination that is
     /// in memory, like a `Vec<u8>`.
     ///
-    /// When the `BufWriter` is dropped, the contents of its buffer will be written
-    /// out. However, any errors that happen in the process of flushing the buffer
-    /// when the writer is dropped will be ignored. Code that wishes to handle such
-    /// errors must manually call [`flush`] before the writer is dropped.
+    /// Unlike the `BufWriter` type in `std`, this type does not write out the
+    /// contents of its buffer when it is dropped. Therefore, it is absolutely
+    /// critical that users explicitly flush the buffer before dropping a
+    /// `BufWriter`.
     ///
-    /// This type is an async version of [`std::io::BufReader`].
+    /// This type is an async version of [`std::io::BufWriter`].
     ///
-    /// [`std::io::BufReader`]: https://doc.rust-lang.org/std/io/struct.BufReader.html
+    /// [`std::io::BufWriter`]: https://doc.rust-lang.org/std/io/struct.BufWriter.html
     ///
     /// # Examples
     ///
@@ -61,10 +61,13 @@ pin_project! {
     /// use async_std::prelude::*;
     ///
     /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").await?);
+    ///
     /// for i in 0..10 {
     ///     let arr = [i+1];
     ///     stream.write(&arr).await?;
     /// };
+    ///
+    /// stream.flush().await?;
     /// #
     /// # Ok(()) }) }
     /// ```
@@ -325,7 +328,7 @@ impl<W: Write> Write for BufWriter<W> {
 
 impl<W: Write + fmt::Debug> fmt::Debug for BufWriter<W> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.debug_struct("BufReader")
+        f.debug_struct("BufWriter")
             .field("writer", &self.inner)
             .field("buf", &self.buf)
             .finish()