Rollup merge of rust-lang#43136 - jgallag88:bufWriterDocs, r=stevekla…

…bnik

Add warning to BufWriter documentation

When using `BufWriter`, it is very easy to unintentionally ignore errors, because errors which occur when flushing buffered data when the `BufWriter` is dropped are ignored. This has been noted in a couple places:  rust-lang#32677, rust-lang#37045.

There has been some discussion about how to fix this problem in rust-lang#32677, but no solution seems likely to land in the near future. For now, anyone who wishes to have robust error handling must remember to manually call `flush()` on a `BufWriter` before it is dropped.  Until a permanent fix is in place, it seems worthwhile to add a warning to that effect to the documentation.

src/libstd/io/buffered.rs

@@ -276,7 +276,10 @@ impl<R: Seek> Seek for BufReader<R> {
 /// `BufWriter` keeps an in-memory buffer of data and writes it to an underlying
 /// writer in large, infrequent batches.
 ///
-/// The buffer will be written out when the writer is dropped.
+/// 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.
 ///
 /// # Examples
 ///
@@ -316,6 +319,7 @@ impl<R: Seek> Seek for BufReader<R> {
 /// [`Write`]: ../../std/io/trait.Write.html
 /// [`Tcpstream::write`]: ../../std/net/struct.TcpStream.html#method.write
 /// [`TcpStream`]: ../../std/net/struct.TcpStream.html
+/// [`flush`]: #method.flush
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct BufWriter<W: Write> {
     inner: Option<W>,