Auto merge of #32465 - steveklabnik:rollup, r=steveklabnik

Rollup of 6 pull requests

- Successful merges: #32276, #32416, #32452, #32459, #32462, #32464
- Failed merges:

7 files changed, 120 insertions, 13 deletions

diff --git a/src/doc/book/drop.md b/src/doc/book/drop.md
index 8bc25ef90d3..5513523e56b 100644
--- a/src/doc/book/drop.md
+++ b/src/doc/book/drop.md
@@ -55,7 +55,7 @@ BOOM times 100!!!
 BOOM times 1!!!
 ```
 
-The TNT goes off before the firecracker does, because it was declared
+The `tnt` goes off before the `firecracker` does, because it was declared
 afterwards. Last in, first out.
 
 So what is `Drop` good for? Generally, `Drop` is used to clean up any resources
diff --git a/src/libcore/clone.rs b/src/libcore/clone.rs
index b1f63ad71ca..a793502e58d 100644
--- a/src/libcore/clone.rs
+++ b/src/libcore/clone.rs
@@ -18,6 +18,29 @@
 //! them cheap and safe to copy. For other types copies must be made
 //! explicitly, by convention implementing the `Clone` trait and calling
 //! the `clone` method.
+//!
+//! Basic usage example:
+//!
+//! ```
+//! let s = String::new(); // String type implements Clone
+//! let copy = s.clone(); // so we can clone it
+//! ```
+//!
+//! To easily implement the Clone trait, you can also use
+//! `#[derive(Clone)]`. Example:
+//!
+//! ```
+//! #[derive(Clone)] // we add the Clone trait to Morpheus struct
+//! struct Morpheus {
+//!    blue_pill: f32,
+//!    red_pill: i64,
+//! }
+//!
+//! fn main() {
+//!    let f = Morpheus { blue_pill: 0.0, red_pill: 0 };
+//!    let copy = f.clone(); // and now we can clone it!
+//! }
+//! ```
 
 #![stable(feature = "rust1", since = "1.0.0")]
 
diff --git a/src/libcore/option.rs b/src/libcore/option.rs
index dd60e8797a9..beed2075d04 100644
--- a/src/libcore/option.rs
+++ b/src/libcore/option.rs
@@ -93,16 +93,12 @@
 //! let msg = Some("howdy");
 //!
 //! // Take a reference to the contained string
-//! match msg {
-//!     Some(ref m) => println!("{}", *m),
-//!     None => (),
+//! if let Some(ref m) = msg {
+//!     println!("{}", *m);
 //! }
 //!
 //! // Remove the contained string, destroying the Option
-//! let unwrapped_msg = match msg {
-//!     Some(m) => m,
-//!     None => "default message",
-//! };
+//! let unwrapped_msg = msg.unwrap_or("default message");
 //! ```
 //!
 //! Initialize a result to `None` before a loop:
diff --git a/src/libstd/io/stdio.rs b/src/libstd/io/stdio.rs
index e1a388c38c4..c4b573db5f2 100644
--- a/src/libstd/io/stdio.rs
+++ b/src/libstd/io/stdio.rs
@@ -141,8 +141,8 @@ fn handle_ebadf<T>(r: io::Result<T>, default: T) -> io::Result<T> {
 ///
 /// Each handle is a shared reference to a global buffer of input data to this
 /// process. A handle can be `lock`'d to gain full access to [`BufRead`] methods
-/// (e.g. `.lines()`). Writes to this handle are otherwise locked with respect
-/// to other writes.
+/// (e.g. `.lines()`). Reads to this handle are otherwise locked with respect
+/// to other reads.
 ///
 /// This handle implements the `Read` trait, but beware that concurrent reads
 /// of `Stdin` must be executed with care.
diff --git a/src/libstd/time/mod.rs b/src/libstd/time/mod.rs
index aa0a843dc9a..0c32feebecb 100644
--- a/src/libstd/time/mod.rs
+++ b/src/libstd/time/mod.rs
@@ -9,6 +9,16 @@
 // except according to those terms.
 
 //! Temporal quantification.
+//!
+//! Example:
+//!
+//! ```
+//! use std::time::Duration;
+//!
+//! let five_seconds = Duration::new(5, 0);
+//! // both declarations are equivalent
+//! assert_eq!(Duration::new(5, 0), Duration::from_secs(5));
+//! ```
 
 #![stable(feature = "time", since = "1.3.0")]
 
@@ -40,6 +50,22 @@ mod duration;
 /// no method to get "the number of seconds" from an instant. Instead, it only
 /// allows measuring the duration between two instants (or comparing two
 /// instants).
+///
+/// Example:
+///
+/// ```no_run
+/// use std::time::{Duration, Instant};
+/// use std::thread::sleep;
+///
+/// fn main() {
+///    let now = Instant::now();
+///
+///    // we sleep for 2 seconds
+///    sleep(Duration::new(2, 0));
+///    // it prints '2'
+///    println!("{}", now.elapsed().as_secs());
+/// }
+/// ```
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 #[stable(feature = "time2", since = "1.8.0")]
 pub struct Instant(time::Instant);
@@ -63,6 +89,30 @@ pub struct Instant(time::Instant);
 /// information about a `SystemTime`. By calculating the duration from this
 /// fixed point in time, a `SystemTime` can be converted to a human-readable time,
 /// or perhaps some other string representation.
+///
+/// Example:
+///
+/// ```no_run
+/// use std::time::{Duration, SystemTime};
+/// use std::thread::sleep;
+///
+/// fn main() {
+///    let now = SystemTime::now();
+///
+///    // we sleep for 2 seconds
+///    sleep(Duration::new(2, 0));
+///    match now.elapsed() {
+///        Ok(elapsed) => {
+///            // it prints '2'
+///            println!("{}", elapsed.as_secs());
+///        }
+///        Err(e) => {
+///            // an error occured!
+///            println!("Error: {:?}", e);
+///        }
+///    }
+/// }
+/// ```
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 #[stable(feature = "time2", since = "1.8.0")]
 pub struct SystemTime(time::SystemTime);
diff --git a/src/libsyntax/errors/json.rs b/src/libsyntax/errors/json.rs
index 5bb5f4757e0..212a54447a8 100644
--- a/src/libsyntax/errors/json.rs
+++ b/src/libsyntax/errors/json.rs
@@ -20,7 +20,7 @@
 // FIXME spec the JSON output properly.
 
 
-use codemap::{MultiSpan, CodeMap};
+use codemap::{Span, MultiSpan, CodeMap};
 use diagnostics::registry::Registry;
 use errors::{Level, DiagnosticBuilder, SubDiagnostic, RenderSpan, CodeSuggestion};
 use errors::emitter::Emitter;
@@ -99,6 +99,16 @@ struct DiagnosticSpan {
     /// 1-based, character offset.
     column_start: usize,
     column_end: usize,
+    /// Source text from the start of line_start to the end of line_end.
+    text: Vec<DiagnosticSpanLine>,
+}
+
+#[derive(RustcEncodable)]
+struct DiagnosticSpanLine {
+    text: String,
+    /// 1-based, character offset in self.text.
+    highlight_start: usize,
+    highlight_end: usize,
 }
 
 #[derive(RustcEncodable)]
@@ -180,6 +190,7 @@ impl DiagnosticSpan {
                 line_end: end.line,
                 column_start: start.col.0 + 1,
                 column_end: end.col.0 + 1,
+                text: DiagnosticSpanLine::from_span(span, je),
             }
         }).collect()
     }
@@ -202,6 +213,7 @@ impl DiagnosticSpan {
                         line_end: end.line,
                         column_start: 0,
                         column_end: end.col.0 + 1,
+                        text: DiagnosticSpanLine::from_span(span, je),
                     }
                 }).collect()
             }
@@ -217,6 +229,7 @@ impl DiagnosticSpan {
                         line_end: end.line,
                         column_start: 0,
                         column_end: 0,
+                        text: DiagnosticSpanLine::from_span(span, je),
                     }
                 }).collect()
             }
@@ -224,6 +237,31 @@ impl DiagnosticSpan {
     }
 }
 
+impl DiagnosticSpanLine {
+    fn from_span(span: &Span, je: &JsonEmitter) -> Vec<DiagnosticSpanLine> {
+        let lines = match je.cm.span_to_lines(*span) {
+            Ok(lines) => lines,
+            Err(_) => {
+                debug!("unprintable span");
+                return Vec::new();
+            }
+        };
+
+        let mut result = Vec::new();
+        let fm = &*lines.file;
+
+        for line in &lines.lines {
+            result.push(DiagnosticSpanLine {
+                text: fm.get_line(line.line_index).unwrap().to_owned(),
+                highlight_start: line.start_col.0 + 1,
+                highlight_end: line.end_col.0 + 1,
+            });
+        }
+
+        result
+    }
+}
+
 impl DiagnosticCode {
     fn map_opt_string(s: Option<String>, je: &JsonEmitter) -> Option<DiagnosticCode> {
         s.map(|s| {
diff --git a/src/test/run-make/json-errors/Makefile b/src/test/run-make/json-errors/Makefile
index bf97f120555..cd3a2af30ab 100644
--- a/src/test/run-make/json-errors/Makefile
+++ b/src/test/run-make/json-errors/Makefile
@@ -6,5 +6,5 @@ all:
 	cp foo.rs $(TMPDIR)
 	cd $(TMPDIR)
 	-$(RUSTC) -Z unstable-options --error-format=json foo.rs 2>$(LOG)
-	grep -q '{"message":"unresolved name `y`","code":{"code":"E0425","explanation":"\\nAn unresolved name was used. Example of erroneous codes.*"},"level":"error","spans":\[{"file_name":"foo.rs","byte_start":496,"byte_end":497,"line_start":12,"line_end":12,"column_start":18,"column_end":19}\],"children":\[\]}' $(LOG)
-	grep -q '{"message":".*","code":{"code":"E0277","explanation":"\\nYou tried.*"},"level":"error","spans":\[{.*}\],"children":\[{"message":"the .*","code":null,"level":"help","spans":\[{"file_name":"foo.rs","byte_start":504,"byte_end":516,"line_start":14,"line_end":14,"column_start":0,"column_end":0}\],"children":\[\]},{"message":"  <u8 as core::ops::Add>","code":null,"level":"help",' $(LOG)
+	grep -q '{"message":"unresolved name `y`","code":{"code":"E0425","explanation":"\\nAn unresolved name was used. Example of erroneous codes.*"},"level":"error","spans":\[{"file_name":"foo.rs","byte_start":496,"byte_end":497,"line_start":12,"line_end":12,"column_start":18,"column_end":19,"text":\[{"text":"    let x = 42 + y;","highlight_start":18,"highlight_end":19}\]}\],"children":\[\]}' $(LOG)
+	grep -q '{"message":".*","code":{"code":"E0277","explanation":"\\nYou tried.*"},"level":"error","spans":\[{.*}\],"children":\[{"message":"the .*","code":null,"level":"help","spans":\[{"file_name":"foo.rs","byte_start":504,"byte_end":516,"line_start":14,"line_end":14,"column_start":0,"column_end":0,"text":\[{.*}\]}\],"children":\[\]},{"message":"  <u8 as core::ops::Add>","code":null,"level":"help",' $(LOG)