From f75e5a7ef4f7cf4f4dae967d351f0e13e51a5447 Mon Sep 17 00:00:00 2001
From: Artem Pyanykh <artem.pyanykh@gmail.com>
Date: Thu, 18 Jun 2020 20:42:28 +0100
Subject: [PATCH] docs: BufWriter does not flush on drop (#2487)

Fixes: #2484
---
 tokio/src/io/mod.rs | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/tokio/src/io/mod.rs b/tokio/src/io/mod.rs
index 216213ea9..7b005560d 100644
--- a/tokio/src/io/mod.rs
+++ b/tokio/src/io/mod.rs
@@ -93,7 +93,8 @@
 //! ```
 //!
 //! [`BufWriter`] doesn't add any new ways of writing; it just buffers every call
-//! to [`write`](crate::io::AsyncWriteExt::write):
+//! to [`write`](crate::io::AsyncWriteExt::write). However, you **must** flush
+//! [`BufWriter`] to ensure that any buffered data is written.
 //!
 //! ```no_run
 //! use tokio::io::{self, BufWriter, AsyncWriteExt};
@@ -105,10 +106,13 @@
 //!     {
 //!         let mut writer = BufWriter::new(f);
 //!
-//!         // write a byte to the buffer
+//!         // Write a byte to the buffer.
 //!         writer.write(&[42u8]).await?;
 //!
-//!     } // the buffer is flushed once writer goes out of scope
+//!         // Flush the buffer before it goes out of scope.
+//!         writer.flush().await?;
+//!
+//!     } // Unless flushed or shut down, the contents of the buffer is discarded on drop.
 //!
 //!     Ok(())
 //! }