2 files changed, 24 insertions, 11 deletions
diff --git a/src/libstd/io/buffered.rs b/src/libstd/io/buffered.rs
index ee297d3783e..189569683a9 100644
--- a/src/libstd/io/buffered.rs
+++ b/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,30 @@ 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")?;
+///
+///     // No bytes are written until a newline is encountered (or
+///     // the internal buffer is filled).
+///     assert_eq!(fs::read_to_string("poem.txt")?, "");
+///     file.write_all(b"\n")?;
+///     assert_eq!(
+///         fs::read_to_string("poem.txt")?,
+///         "I shall be telling this with a sigh\n",
+///     );
 ///
-///     // let's check we did the right thing.
-///     let mut file = File::open("poem.txt")?;
-///     let mut contents = String::new();
+///     // 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.")?;
 ///
-///     file.read_to_string(&mut contents)?;
+///     // 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()?;
 ///
-///     assert_eq!(contents.as_bytes(), &road_not_taken[..]);
+///     // Confirm the whole poem was written.
+///     assert_eq!(fs::read("poem.txt")?, &road_not_taken[..]);
 ///     Ok(())
 /// }
 /// ```
@@ -862,7 +875,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.
     ///
diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs
index 0f60b5b3ee4..6b4bbdddf32 100644
--- a/src/libstd/net/tcp.rs
+++ b/src/libstd/net/tcp.rs
@@ -81,7 +81,7 @@ pub struct TcpStream(net_imp::TcpStream);
 /// }
 ///
 /// fn main() -> io::Result<()> {
-///     let listener = TcpListener::bind("127.0.0.1:80").unwrap();
+///     let listener = TcpListener::bind("127.0.0.1:80")?;
 ///
 ///     // accept connections and process them serially
 ///     for stream in listener.incoming() {