rework LineWriter example

The original example didn't check the return value of `write()`, didn't
flush the writer, and didn't properly demonstrate the buffering.

Fixes #51621.

src/libstd/io/buffered.rs

@@ -738,7 +738,7 @@ impl<W> fmt::Display for IntoInnerError<W> {
 /// reducing the number of actual writes to the file.
 ///
 /// ```no_run
-/// use std::fs::File;
+/// use std::fs::{self, File};
 /// use std::io::prelude::*;
 /// use std::io::LineWriter;
 ///
@@ -752,17 +752,31 @@ impl<W> fmt::Display for IntoInnerError<W> {
 ///     let file = File::create("poem.txt")?;
 ///     let mut file = LineWriter::new(file);
 ///
-///     for &byte in road_not_taken.iter() {
-///        file.write(&[byte]).unwrap();
-///     }
+///     file.write_all(b"I shall be telling this with a sigh")?;
 ///
-///     // let's check we did the right thing.
-///     let mut file = File::open("poem.txt")?;
-///     let mut contents = String::new();
+///     // No bytes are written until a newline is encountered (or
+///     // the internal buffer is filled).
+///     assert_eq!(fs::read_to_string("poem.txt")?.as_bytes(), b"");
+///     file.write_all(b"\n")?;
+///     assert_eq!(
+///         fs::read_to_string("poem.txt")?.as_bytes(),
+///         &b"I shall be telling this with a sigh\n"[..],
+///     );
 ///
-///     file.read_to_string(&mut contents)?;
+///     // Write the rest of the poem.
+///     file.write_all(b"Somewhere ages and ages hence:
+/// Two roads diverged in a wood, and I -
+/// I took the one less traveled by,
+/// And that has made all the difference.")?;
 ///
-///     assert_eq!(contents.as_bytes(), &road_not_taken[..]);
+///     // The last line of the poem doesn't end in a newline, so
+///     // we have to flush or drop the `LineWriter` to finish
+///     // writing.
+///     file.flush()?;
+///
+///     // Confirm the whole poem was written.
+///     let mut poem = fs::read_to_string("poem.txt")?;
+///     assert_eq!(poem.as_bytes(), &road_not_taken[..]);
 ///     Ok(())
 /// }
 /// ```
@@ -862,7 +876,7 @@ impl<W: Write> LineWriter<W> {
     ///
     /// The internal buffer is written out before returning the writer.
     ///
-    // # Errors
+    /// # Errors
     ///
     /// An `Err` will be returned if an error occurs while flushing the buffer.
     ///