From bc3fbd9713dba8810d10a8de01c339fe42760ca1 Mon Sep 17 00:00:00 2001 From: Without Boats Date: Tue, 26 Nov 2019 14:11:09 +0100 Subject: [PATCH] Fix the docs and Debug output of BufWriter. 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 ce6a97b37..c527d0270 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`. /// - /// 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 Write for BufWriter { impl fmt::Debug for BufWriter { 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()