diff --git a/src/doc/book/compiler-plugins.md b/src/doc/book/compiler-plugins.md
index 8426d5a626549..a9a81843ab199 100644
--- a/src/doc/book/compiler-plugins.md
+++ b/src/doc/book/compiler-plugins.md
@@ -46,10 +46,10 @@ extern crate rustc;
 extern crate rustc_plugin;
 
 use syntax::parse::token;
-use syntax::ast::TokenTree;
+use syntax::tokenstream::TokenTree;
 use syntax::ext::base::{ExtCtxt, MacResult, DummyResult, MacEager};
 use syntax::ext::build::AstBuilder;  // trait for expr_usize
-use syntax_pos::Span;
+use syntax::ext::quote::rt::Span;
 use rustc_plugin::Registry;
 
 fn expand_rn(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
@@ -69,7 +69,7 @@ fn expand_rn(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
     }
 
     let text = match args[0] {
-        TokenTree::Token(_, token::Ident(s, _)) => s.to_string(),
+        TokenTree::Token(_, token::Ident(s)) => s.to_string(),
         _ => {
             cx.span_err(sp, "argument should be a single identifier");
             return DummyResult::any(sp);
diff --git a/src/libcollections/fmt.rs b/src/libcollections/fmt.rs
index b7cbfb60ec4e9..beb3e6b3d4e31 100644
--- a/src/libcollections/fmt.rs
+++ b/src/libcollections/fmt.rs
@@ -165,9 +165,15 @@
 //! provides some helper methods.
 //!
 //! Additionally, the return value of this function is `fmt::Result` which is a
-//! typedef to `Result<(), std::io::Error>` (also known as `std::io::Result<()>`).
-//! Formatting implementations should ensure that they return errors from `write!`
-//! correctly (propagating errors upward).
+//! type alias of `Result<(), std::fmt::Error>`. Formatting implementations
+//! should ensure that they propagate errors from the `Formatter` (e.g., when
+//! calling `write!`) however, they should never return errors spuriously. That
+//! is, a formatting implementation must and may only return an error if the
+//! passed-in `Formatter` returns an error. This is because, contrary to what
+//! the function signature might suggest, string formatting is an infallible
+//! operation. This function only returns a result because writing to the
+//! underlying stream might fail and it must provide a way to propagate the fact
+//! that an error has occurred back up the stack.
 //!
 //! An example of implementing the formatting traits would look
 //! like:
diff --git a/src/libcore/intrinsics.rs b/src/libcore/intrinsics.rs
index 8271b85b01a3b..761f1cac8392b 100644
--- a/src/libcore/intrinsics.rs
+++ b/src/libcore/intrinsics.rs
@@ -222,15 +222,20 @@ extern "rust-intrinsic" {
     ///   trait objects, because they can't be read out onto the stack and
     ///   dropped normally.
     ///
-    /// * It is friendlier to the optimizer to do this over `ptr::read` when
-    ///   dropping manually allocated memory (e.g. when writing Box/Rc/Vec),
-    ///   as the compiler doesn't need to prove that it's sound to elide the
-    ///   copy.
+    /// * It is friendlier to the optimizer to do this over [`ptr::read`] when
+    ///   dropping manually allocated memory (e.g. when writing
+    ///   [`Box`]/[`Rc`]/[`Vec`]), as the compiler doesn't need to prove that
+    ///   it's sound to elide the copy.
     ///
     /// # Undefined Behavior
     ///
-    /// This has all the same safety problems as `ptr::read` with respect to
+    /// This has all the same safety problems as [`ptr::read`] with respect to
     /// invalid pointers, types, and double drops.
+    ///
+    /// [`ptr::read`]: fn.read.html
+    /// [`Box`]: ../boxed/struct.Box.html
+    /// [`Rc`]: ../rc/struct.Rc.html
+    /// [`Vec`]: ../vec/struct.Vec.html
     #[stable(feature = "drop_in_place", since = "1.8.0")]
     pub fn drop_in_place<T: ?Sized>(to_drop: *mut T);
 
diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs
index b9adaf0206d94..42358fd7f986d 100644
--- a/src/libcore/ops.rs
+++ b/src/libcore/ops.rs
@@ -68,6 +68,26 @@
 //! ```
 //!
 //! See the documentation for each trait for an example implementation.
+//!
+//! This example shows the behavior of the various `Range*` structs.
+//!
+//! ```rust
+//! #![feature(inclusive_range_syntax)]
+//! fn main() {
+//!     let arr = [0, 1, 2, 3, 4];
+//!
+//!     assert_eq!(arr[ .. ], [0,1,2,3,4]); // RangeFull
+//!     assert_eq!(arr[ ..3], [0,1,2    ]); // RangeTo
+//!     assert_eq!(arr[1.. ], [  1,2,3,4]); // RangeFrom
+//!     assert_eq!(arr[1..3], [  1,2    ]); // Range
+//!
+//!     assert_eq!(arr[ ...3], [0,1,2,3 ]); // RangeToIncusive
+//!     assert_eq!(arr[1...3], [  1,2,3 ]); // RangeInclusive
+//! }
+//! ```
+//!
+//! Note: whitespace alignment is not idiomatic Rust. An exception is made in
+//! this case to facilitate comparison.
 
 #![stable(feature = "rust1", since = "1.0.0")]
 
@@ -967,25 +987,54 @@ bitxor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 ///
 /// # Examples
 ///
-/// A trivial implementation of `Shl`. When `Foo << Foo` happens, it ends up
-/// calling `shl`, and therefore, `main` prints `Shifting left!`.
+/// An implementation of `Shl` that lifts the `<<` operation on integers to a
+/// `Scalar` struct.
 ///
 /// ```
 /// use std::ops::Shl;
 ///
-/// struct Foo;
+/// #[derive(PartialEq, Debug)]
+/// struct Scalar(usize);
 ///
-/// impl Shl<Foo> for Foo {
-///     type Output = Foo;
+/// impl Shl<Scalar> for Scalar {
+///     type Output = Self;
 ///
-///     fn shl(self, _rhs: Foo) -> Foo {
-///         println!("Shifting left!");
-///         self
+///     fn shl(self, Scalar(rhs): Self) -> Scalar {
+///         let Scalar(lhs) = self;
+///         Scalar(lhs << rhs)
+///     }
+/// }
+/// fn main() {
+///     assert_eq!(Scalar(4) << Scalar(2), Scalar(16));
+/// }
+/// ```
+///
+/// An implementation of `Shl` that spins a vector leftward by a given amount.
+///
+/// ```
+/// use std::ops::Shl;
+///
+/// #[derive(PartialEq, Debug)]
+/// struct SpinVector<T: Clone> {
+///     vec: Vec<T>,
+/// }
+///
+/// impl<T: Clone> Shl<usize> for SpinVector<T> {
+///     type Output = Self;
+///
+///     fn shl(self, rhs: usize) -> SpinVector<T> {
+///         // rotate the vector by `rhs` places
+///         let (a, b) = self.vec.split_at(rhs);
+///         let mut spun_vector: Vec<T> = vec![];
+///         spun_vector.extend_from_slice(b);
+///         spun_vector.extend_from_slice(a);
+///         SpinVector { vec: spun_vector }
 ///     }
 /// }
 ///
 /// fn main() {
-///     Foo << Foo;
+///     assert_eq!(SpinVector { vec: vec![0, 1, 2, 3, 4] } << 2,
+///                SpinVector { vec: vec![2, 3, 4, 0, 1] });
 /// }
 /// ```
 #[lang = "shl"]
@@ -1039,25 +1088,54 @@ shl_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 ///
 /// # Examples
 ///
-/// A trivial implementation of `Shr`. When `Foo >> Foo` happens, it ends up
-/// calling `shr`, and therefore, `main` prints `Shifting right!`.
+/// An implementation of `Shr` that lifts the `>>` operation on integers to a
+/// `Scalar` struct.
 ///
 /// ```
 /// use std::ops::Shr;
 ///
-/// struct Foo;
+/// #[derive(PartialEq, Debug)]
+/// struct Scalar(usize);
 ///
-/// impl Shr<Foo> for Foo {
-///     type Output = Foo;
+/// impl Shr<Scalar> for Scalar {
+///     type Output = Self;
 ///
-///     fn shr(self, _rhs: Foo) -> Foo {
-///         println!("Shifting right!");
-///         self
+///     fn shr(self, Scalar(rhs): Self) -> Scalar {
+///         let Scalar(lhs) = self;
+///         Scalar(lhs >> rhs)
+///     }
+/// }
+/// fn main() {
+///     assert_eq!(Scalar(16) >> Scalar(2), Scalar(4));
+/// }
+/// ```
+///
+/// An implementation of `Shr` that spins a vector rightward by a given amount.
+///
+/// ```
+/// use std::ops::Shr;
+///
+/// #[derive(PartialEq, Debug)]
+/// struct SpinVector<T: Clone> {
+///     vec: Vec<T>,
+/// }
+///
+/// impl<T: Clone> Shr<usize> for SpinVector<T> {
+///     type Output = Self;
+///
+///     fn shr(self, rhs: usize) -> SpinVector<T> {
+///         // rotate the vector by `rhs` places
+///         let (a, b) = self.vec.split_at(self.vec.len() - rhs);
+///         let mut spun_vector: Vec<T> = vec![];
+///         spun_vector.extend_from_slice(b);
+///         spun_vector.extend_from_slice(a);
+///         SpinVector { vec: spun_vector }
 ///     }
 /// }
 ///
 /// fn main() {
-///     Foo >> Foo;
+///     assert_eq!(SpinVector { vec: vec![0, 1, 2, 3, 4] } >> 2,
+///                SpinVector { vec: vec![3, 4, 0, 1, 2] });
 /// }
 /// ```
 #[lang = "shr"]
@@ -1736,11 +1814,12 @@ pub trait IndexMut<Idx: ?Sized>: Index<Idx> {
 ///
 /// ```
 /// let arr = [0, 1, 2, 3];
-/// assert_eq!(arr[ .. ], [0,1,2,3]);  // RangeFull
-/// assert_eq!(arr[ ..3], [0,1,2  ]);
-/// assert_eq!(arr[1.. ], [  1,2,3]);
-/// assert_eq!(arr[1..3], [  1,2  ]);
+/// assert_eq!(arr[ .. ], [0, 1, 2, 3]);
 /// ```
+///
+/// See the [module examples] for the behavior of other range structs.
+///
+/// [module examples]: ../#Examples
 #[derive(Copy, Clone, PartialEq, Eq, Hash)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct RangeFull;
@@ -1765,12 +1844,13 @@ impl fmt::Debug for RangeFull {
 ///     assert_eq!(3+4+5, (3..6).sum());
 ///
 ///     let arr = [0, 1, 2, 3];
-///     assert_eq!(arr[ .. ], [0,1,2,3]);
-///     assert_eq!(arr[ ..3], [0,1,2  ]);
-///     assert_eq!(arr[1.. ], [  1,2,3]);
-///     assert_eq!(arr[1..3], [  1,2  ]);  // Range
+///     assert_eq!(arr[1..3], [1, 2]);
 /// }
 /// ```
+///
+/// See the [module examples] for the behavior of other range structs.
+///
+/// [module examples]: ../#Examples
 #[derive(Clone, PartialEq, Eq, Hash)]  // not Copy -- see #27186
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Range<Idx> {
@@ -1828,12 +1908,13 @@ impl<Idx: PartialOrd<Idx>> Range<Idx> {
 ///     assert_eq!(2+3+4, (2..).take(3).sum());
 ///
 ///     let arr = [0, 1, 2, 3];
-///     assert_eq!(arr[ .. ], [0,1,2,3]);
-///     assert_eq!(arr[ ..3], [0,1,2  ]);
-///     assert_eq!(arr[1.. ], [  1,2,3]);  // RangeFrom
-///     assert_eq!(arr[1..3], [  1,2  ]);
+///     assert_eq!(arr[1.. ], [1, 2, 3]);
 /// }
 /// ```
+///
+/// See the [module examples] for the behavior of other range structs.
+///
+/// [module examples]: ../#Examples
 #[derive(Clone, PartialEq, Eq, Hash)]  // not Copy -- see #27186
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct RangeFrom<Idx> {
@@ -1878,12 +1959,13 @@ impl<Idx: PartialOrd<Idx>> RangeFrom<Idx> {
 ///     assert_eq!((..5), std::ops::RangeTo{ end: 5 });
 ///
 ///     let arr = [0, 1, 2, 3];
-///     assert_eq!(arr[ .. ], [0,1,2,3]);
-///     assert_eq!(arr[ ..3], [0,1,2  ]);  // RangeTo
-///     assert_eq!(arr[1.. ], [  1,2,3]);
-///     assert_eq!(arr[1..3], [  1,2  ]);
+///     assert_eq!(arr[ ..3], [0, 1, 2]);
 /// }
 /// ```
+///
+/// See the [module examples] for the behavior of other range structs.
+///
+/// [module examples]: ../#Examples
 #[derive(Copy, Clone, PartialEq, Eq, Hash)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct RangeTo<Idx> {
@@ -1930,10 +2012,13 @@ impl<Idx: PartialOrd<Idx>> RangeTo<Idx> {
 ///     assert_eq!(3+4+5, (3...5).sum());
 ///
 ///     let arr = [0, 1, 2, 3];
-///     assert_eq!(arr[ ...2], [0,1,2  ]);
-///     assert_eq!(arr[1...2], [  1,2  ]);  // RangeInclusive
+///     assert_eq!(arr[1...2], [1, 2]);
 /// }
 /// ```
+///
+/// See the [module examples] for the behavior of other range structs.
+///
+/// [module examples]: ../#Examples
 #[derive(Clone, PartialEq, Eq, Hash)]  // not Copy -- see #27186
 #[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")]
 pub enum RangeInclusive<Idx> {
@@ -2017,10 +2102,13 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
 ///     assert_eq!((...5), std::ops::RangeToInclusive{ end: 5 });
 ///
 ///     let arr = [0, 1, 2, 3];
-///     assert_eq!(arr[ ...2], [0,1,2  ]);  // RangeToInclusive
-///     assert_eq!(arr[1...2], [  1,2  ]);
+///     assert_eq!(arr[ ...2], [0, 1, 2]);
 /// }
 /// ```
+///
+/// See the [module examples] for the behavior of other range structs.
+///
+/// [module examples]: ../#Examples
 #[derive(Copy, Clone, PartialEq, Eq, Hash)]
 #[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")]
 pub struct RangeToInclusive<Idx> {
diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs
index 8c8925251e5cf..974a4b7fd4c16 100644
--- a/src/libcore/ptr.rs
+++ b/src/libcore/ptr.rs
@@ -111,11 +111,17 @@ pub unsafe fn replace<T>(dest: *mut T, mut src: T) -> T {
 /// # Safety
 ///
 /// Beyond accepting a raw pointer, this is unsafe because it semantically
-/// moves the value out of `src` without preventing further usage of `src`.
-/// If `T` is not `Copy`, then care must be taken to ensure that the value at
-/// `src` is not used before the data is overwritten again (e.g. with `write`,
-/// `zero_memory`, or `copy_memory`). Note that `*src = foo` counts as a use
-/// because it will attempt to drop the value previously at `*src`.
+/// moves the value out of `src` without preventing further usage of `src`. If
+/// `T` is not [`Copy`], then care must be taken to ensure that the value at
+/// `src` is not used before the data is overwritten again (e.g. with
+/// [`write`], [`zero_memory`], or [`copy_memory`]). Note that `*src = foo`
+/// counts as a use because it will attempt to drop the value previously at
+/// `*src`.
+///
+/// [`Copy`]: ../marker/trait.Copy.html
+/// [`write`]: fn.write.html
+/// [`zero_memory`]: fn.zero_memory.html
+/// [`copy_memory`]: fn.copy_memory.html
 ///
 /// # Examples
 ///
@@ -190,11 +196,17 @@ pub unsafe fn write<T>(dst: *mut T, src: T) {
 /// # Safety
 ///
 /// Beyond accepting a raw pointer, this is unsafe because it semantically
-/// moves the value out of `src` without preventing further usage of `src`.
-/// If `T` is not `Copy`, then care must be taken to ensure that the value at
-/// `src` is not used before the data is overwritten again (e.g. with `write`,
-/// `zero_memory`, or `copy_memory`). Note that `*src = foo` counts as a use
-/// because it will attempt to drop the value previously at `*src`.
+/// moves the value out of `src` without preventing further usage of `src`. If
+/// `T` is not [`Copy`], then care must be taken to ensure that the value at
+/// `src` is not used before the data is overwritten again (e.g. with
+/// [`write`], [`zero_memory`], or [`copy_memory`]). Note that `*src = foo`
+/// counts as a use because it will attempt to drop the value previously at
+/// `*src`.
+///
+/// [`Copy`]: ../marker/trait.Copy.html
+/// [`write`]: fn.write.html
+/// [`zero_memory`]: fn.zero_memory.html
+/// [`copy_memory`]: fn.copy_memory.html
 ///
 /// # Examples
 ///
diff --git a/src/librbml/lib.rs b/src/librbml/lib.rs
index 1825a892cf554..5a8a52f7dfc6e 100644
--- a/src/librbml/lib.rs
+++ b/src/librbml/lib.rs
@@ -726,7 +726,7 @@ pub mod reader {
         fn read_u8(&mut self) -> DecodeResult<u8> {
             Ok(doc_as_u8(self.next_doc(EsU8)?))
         }
-        fn read_uint(&mut self) -> DecodeResult<usize> {
+        fn read_usize(&mut self) -> DecodeResult<usize> {
             let v = self._next_int(EsU8, EsU64)?;
             if v > (::std::usize::MAX as u64) {
                 Err(IntTooBig(v as usize))
@@ -747,7 +747,7 @@ pub mod reader {
         fn read_i8(&mut self) -> DecodeResult<i8> {
             Ok(doc_as_u8(self.next_doc(EsI8)?) as i8)
         }
-        fn read_int(&mut self) -> DecodeResult<isize> {
+        fn read_isize(&mut self) -> DecodeResult<isize> {
             let v = self._next_int(EsI8, EsI64)? as i64;
             if v > (isize::MAX as i64) || v < (isize::MIN as i64) {
                 debug!("FIXME \\#6122: Removing this makes this function miscompile");
@@ -1219,7 +1219,7 @@ pub mod writer {
             Ok(())
         }
 
-        fn emit_uint(&mut self, v: usize) -> EncodeResult {
+        fn emit_usize(&mut self, v: usize) -> EncodeResult {
             self.emit_u64(v as u64)
         }
         fn emit_u64(&mut self, v: u64) -> EncodeResult {
@@ -1247,7 +1247,7 @@ pub mod writer {
             self.wr_tagged_raw_u8(EsU8 as usize, v)
         }
 
-        fn emit_int(&mut self, v: isize) -> EncodeResult {
+        fn emit_isize(&mut self, v: isize) -> EncodeResult {
             self.emit_i64(v as i64)
         }
         fn emit_i64(&mut self, v: i64) -> EncodeResult {
diff --git a/src/librbml/opaque.rs b/src/librbml/opaque.rs
index 10f419d169181..6dc7a72b1b1bb 100644
--- a/src/librbml/opaque.rs
+++ b/src/librbml/opaque.rs
@@ -54,7 +54,7 @@ impl<'a> serialize::Encoder for Encoder<'a> {
         Ok(())
     }
 
-    fn emit_uint(&mut self, v: usize) -> EncodeResult {
+    fn emit_usize(&mut self, v: usize) -> EncodeResult {
         write_uleb128!(self, v)
     }
 
@@ -75,7 +75,7 @@ impl<'a> serialize::Encoder for Encoder<'a> {
         Ok(())
     }
 
-    fn emit_int(&mut self, v: isize) -> EncodeResult {
+    fn emit_isize(&mut self, v: isize) -> EncodeResult {
         write_sleb128!(self, v)
     }
 
@@ -120,7 +120,7 @@ impl<'a> serialize::Encoder for Encoder<'a> {
     }
 
     fn emit_str(&mut self, v: &str) -> EncodeResult {
-        self.emit_uint(v.len())?;
+        self.emit_usize(v.len())?;
         let _ = self.cursor.write_all(v.as_bytes());
         Ok(())
     }
@@ -139,7 +139,7 @@ impl<'a> serialize::Encoder for Encoder<'a> {
                             -> EncodeResult
         where F: FnOnce(&mut Self) -> EncodeResult
     {
-        self.emit_uint(v_id)?;
+        self.emit_usize(v_id)?;
         f(self)
     }
 
@@ -221,7 +221,7 @@ impl<'a> serialize::Encoder for Encoder<'a> {
     fn emit_seq<F>(&mut self, len: usize, f: F) -> EncodeResult
         where F: FnOnce(&mut Encoder<'a>) -> EncodeResult
     {
-        self.emit_uint(len)?;
+        self.emit_usize(len)?;
         f(self)
     }
 
@@ -234,7 +234,7 @@ impl<'a> serialize::Encoder for Encoder<'a> {
     fn emit_map<F>(&mut self, len: usize, f: F) -> EncodeResult
         where F: FnOnce(&mut Encoder<'a>) -> EncodeResult
     {
-        self.emit_uint(len)?;
+        self.emit_usize(len)?;
         f(self)
     }
 
@@ -329,7 +329,7 @@ impl<'a> serialize::Decoder for Decoder<'a> {
         Ok(value)
     }
 
-    fn read_uint(&mut self) -> Result<usize, Self::Error> {
+    fn read_usize(&mut self) -> Result<usize, Self::Error> {
         read_uleb128!(self, usize)
     }
 
@@ -351,7 +351,7 @@ impl<'a> serialize::Decoder for Decoder<'a> {
         unsafe { Ok(::std::mem::transmute(as_u8)) }
     }
 
-    fn read_int(&mut self) -> Result<isize, Self::Error> {
+    fn read_isize(&mut self) -> Result<isize, Self::Error> {
         read_sleb128!(self, isize)
     }
 
@@ -376,7 +376,7 @@ impl<'a> serialize::Decoder for Decoder<'a> {
     }
 
     fn read_str(&mut self) -> Result<String, Self::Error> {
-        let len = self.read_uint()?;
+        let len = self.read_usize()?;
         let s = ::std::str::from_utf8(&self.data[self.position..self.position + len]).unwrap();
         self.position += len;
         Ok(s.to_string())
@@ -391,7 +391,7 @@ impl<'a> serialize::Decoder for Decoder<'a> {
     fn read_enum_variant<T, F>(&mut self, _: &[&str], mut f: F) -> Result<T, Self::Error>
         where F: FnMut(&mut Decoder<'a>, usize) -> Result<T, Self::Error>
     {
-        let disr = self.read_uint()?;
+        let disr = self.read_usize()?;
         f(self, disr)
     }
 
@@ -404,7 +404,7 @@ impl<'a> serialize::Decoder for Decoder<'a> {
     fn read_enum_struct_variant<T, F>(&mut self, _: &[&str], mut f: F) -> Result<T, Self::Error>
         where F: FnMut(&mut Decoder<'a>, usize) -> Result<T, Self::Error>
     {
-        let disr = self.read_uint()?;
+        let disr = self.read_usize()?;
         f(self, disr)
     }
 
@@ -483,7 +483,7 @@ impl<'a> serialize::Decoder for Decoder<'a> {
     fn read_seq<T, F>(&mut self, f: F) -> Result<T, Self::Error>
         where F: FnOnce(&mut Decoder<'a>, usize) -> Result<T, Self::Error>
     {
-        let len = self.read_uint()?;
+        let len = self.read_usize()?;
         f(self, len)
     }
 
@@ -496,7 +496,7 @@ impl<'a> serialize::Decoder for Decoder<'a> {
     fn read_map<T, F>(&mut self, f: F) -> Result<T, Self::Error>
         where F: FnOnce(&mut Decoder<'a>, usize) -> Result<T, Self::Error>
     {
-        let len = self.read_uint()?;
+        let len = self.read_usize()?;
         f(self, len)
     }
 
diff --git a/src/librustc_borrowck/borrowck/mod.rs b/src/librustc_borrowck/borrowck/mod.rs
index 6137afbb59f4d..e8b44d85bf916 100644
--- a/src/librustc_borrowck/borrowck/mod.rs
+++ b/src/librustc_borrowck/borrowck/mod.rs
@@ -926,9 +926,11 @@ impl<'a, 'tcx> BorrowckCtxt<'a, 'tcx> {
                 err
             }
             mc::AliasableBorrowed => {
-                struct_span_err!(
+                let mut e = struct_span_err!(
                     self.tcx.sess, span, E0389,
-                    "{} in a `&` reference", prefix)
+                    "{} in a `&` reference", prefix);
+                e.span_label(span, &"assignment into an immutable reference");
+                e
             }
         };
 
diff --git a/src/libserialize/collection_impls.rs b/src/libserialize/collection_impls.rs
index 5d652ba2f55bb..7b5092e8848e4 100644
--- a/src/libserialize/collection_impls.rs
+++ b/src/libserialize/collection_impls.rs
@@ -136,7 +136,7 @@ impl<
         for item in self {
             bits |= item.to_usize();
         }
-        s.emit_uint(bits)
+        s.emit_usize(bits)
     }
 }
 
@@ -144,7 +144,7 @@ impl<
     T: Decodable + CLike
 > Decodable for EnumSet<T> {
     fn decode<D: Decoder>(d: &mut D) -> Result<EnumSet<T>, D::Error> {
-        let bits = d.read_uint()?;
+        let bits = d.read_usize()?;
         let mut set = EnumSet::new();
         for bit in 0..(mem::size_of::<usize>()*8) {
             if bits & (1 << bit) != 0 {
diff --git a/src/libserialize/json.rs b/src/libserialize/json.rs
index 6c4b6c4506b81..34df594e84756 100644
--- a/src/libserialize/json.rs
+++ b/src/libserialize/json.rs
@@ -495,13 +495,13 @@ impl<'a> ::Encoder for Encoder<'a> {
         Ok(())
     }
 
-    fn emit_uint(&mut self, v: usize) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
+    fn emit_usize(&mut self, v: usize) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
     fn emit_u64(&mut self, v: u64) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
     fn emit_u32(&mut self, v: u32) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
     fn emit_u16(&mut self, v: u16) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
     fn emit_u8(&mut self, v: u8) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
 
-    fn emit_int(&mut self, v: isize) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
+    fn emit_isize(&mut self, v: isize) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
     fn emit_i64(&mut self, v: i64) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
     fn emit_i32(&mut self, v: i32) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
     fn emit_i16(&mut self, v: i16) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
@@ -743,13 +743,13 @@ impl<'a> ::Encoder for PrettyEncoder<'a> {
         Ok(())
     }
 
-    fn emit_uint(&mut self, v: usize) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
+    fn emit_usize(&mut self, v: usize) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
     fn emit_u64(&mut self, v: u64) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
     fn emit_u32(&mut self, v: u32) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
     fn emit_u16(&mut self, v: u16) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
     fn emit_u8(&mut self, v: u8) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
 
-    fn emit_int(&mut self, v: isize) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
+    fn emit_isize(&mut self, v: isize) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
     fn emit_i64(&mut self, v: i64) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
     fn emit_i32(&mut self, v: i32) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
     fn emit_i16(&mut self, v: i16) -> EncodeResult { emit_enquoted_if_mapkey!(self, v) }
@@ -2137,12 +2137,12 @@ impl ::Decoder for Decoder {
         expect!(self.pop(), Null)
     }
 
-    read_primitive! { read_uint, usize }
+    read_primitive! { read_usize, usize }
     read_primitive! { read_u8, u8 }
     read_primitive! { read_u16, u16 }
     read_primitive! { read_u32, u32 }
     read_primitive! { read_u64, u64 }
-    read_primitive! { read_int, isize }
+    read_primitive! { read_isize, isize }
     read_primitive! { read_i8, i8 }
     read_primitive! { read_i16, i16 }
     read_primitive! { read_i32, i32 }
diff --git a/src/libserialize/serialize.rs b/src/libserialize/serialize.rs
index 0fcab1347d160..b75ec5dad8ddd 100644
--- a/src/libserialize/serialize.rs
+++ b/src/libserialize/serialize.rs
@@ -24,12 +24,12 @@ pub trait Encoder {
 
     // Primitive types:
     fn emit_nil(&mut self) -> Result<(), Self::Error>;
-    fn emit_uint(&mut self, v: usize) -> Result<(), Self::Error>;
+    fn emit_usize(&mut self, v: usize) -> Result<(), Self::Error>;
     fn emit_u64(&mut self, v: u64) -> Result<(), Self::Error>;
     fn emit_u32(&mut self, v: u32) -> Result<(), Self::Error>;
     fn emit_u16(&mut self, v: u16) -> Result<(), Self::Error>;
     fn emit_u8(&mut self, v: u8) -> Result<(), Self::Error>;
-    fn emit_int(&mut self, v: isize) -> Result<(), Self::Error>;
+    fn emit_isize(&mut self, v: isize) -> Result<(), Self::Error>;
     fn emit_i64(&mut self, v: i64) -> Result<(), Self::Error>;
     fn emit_i32(&mut self, v: i32) -> Result<(), Self::Error>;
     fn emit_i16(&mut self, v: i16) -> Result<(), Self::Error>;
@@ -108,12 +108,12 @@ pub trait Decoder {
 
     // Primitive types:
     fn read_nil(&mut self) -> Result<(), Self::Error>;
-    fn read_uint(&mut self) -> Result<usize, Self::Error>;
+    fn read_usize(&mut self) -> Result<usize, Self::Error>;
     fn read_u64(&mut self) -> Result<u64, Self::Error>;
     fn read_u32(&mut self) -> Result<u32, Self::Error>;
     fn read_u16(&mut self) -> Result<u16, Self::Error>;
     fn read_u8(&mut self) -> Result<u8, Self::Error>;
-    fn read_int(&mut self) -> Result<isize, Self::Error>;
+    fn read_isize(&mut self) -> Result<isize, Self::Error>;
     fn read_i64(&mut self) -> Result<i64, Self::Error>;
     fn read_i32(&mut self) -> Result<i32, Self::Error>;
     fn read_i16(&mut self) -> Result<i16, Self::Error>;
@@ -200,13 +200,13 @@ pub trait Decodable: Sized {
 
 impl Encodable for usize {
     fn encode<S: Encoder>(&self, s: &mut S) -> Result<(), S::Error> {
-        s.emit_uint(*self)
+        s.emit_usize(*self)
     }
 }
 
 impl Decodable for usize {
     fn decode<D: Decoder>(d: &mut D) -> Result<usize, D::Error> {
-        d.read_uint()
+        d.read_usize()
     }
 }
 
@@ -260,13 +260,13 @@ impl Decodable for u64 {
 
 impl Encodable for isize {
     fn encode<S: Encoder>(&self, s: &mut S) -> Result<(), S::Error> {
-        s.emit_int(*self)
+        s.emit_isize(*self)
     }
 }
 
 impl Decodable for isize {
     fn decode<D: Decoder>(d: &mut D) -> Result<isize, D::Error> {
-        d.read_int()
+        d.read_isize()
     }
 }
 
diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs
index f2374e722c1e3..0deb9f38a937c 100644
--- a/src/libstd/fs.rs
+++ b/src/libstd/fs.rs
@@ -1510,8 +1510,11 @@ pub fn remove_dir_all<P: AsRef<Path>>(path: P) -> io::Result<()> {
 
 /// Returns an iterator over the entries within a directory.
 ///
-/// The iterator will yield instances of `io::Result<DirEntry>`. New errors may
-/// be encountered after an iterator is initially constructed.
+/// The iterator will yield instances of [`io::Result<`][`DirEntry`]`>`.
+/// New errors may be encountered after an iterator is initially constructed.
+///
+/// [`io::Result<`]: ../io/type.Result.html
+/// [`DirEntry`]: struct.DirEntry.html
 ///
 /// # Platform-specific behavior
 ///
diff --git a/src/libstd/path.rs b/src/libstd/path.rs
index 67219b6fd1b9c..df3d370e9f58d 100644
--- a/src/libstd/path.rs
+++ b/src/libstd/path.rs
@@ -990,11 +990,16 @@ impl<'a> cmp::Ord for Components<'a> {
 // Basic types and traits
 ////////////////////////////////////////////////////////////////////////////////
 
-/// An owned, mutable path (akin to `String`).
+/// An owned, mutable path (akin to [`String`]).
 ///
-/// This type provides methods like `push` and `set_extension` that mutate the
-/// path in place. It also implements `Deref` to `Path`, meaning that all
-/// methods on `Path` slices are available on `PathBuf` values as well.
+/// This type provides methods like [`push`] and [`set_extension`] that mutate
+/// the path in place. It also implements [`Deref`] to [`Path`], meaning that
+/// all methods on [`Path`] slices are available on `PathBuf` values as well.
+///
+/// [`String`]: ../string/struct.String.html
+/// [`Path`]: struct.Path.html
+/// [`push`]: struct.PathBuf.html#method.push
+/// [`set_extension`]: struct.PathBuf.html#method.set_extension
 ///
 /// More details about the overall approach can be found in
 /// the module documentation.
@@ -1021,12 +1026,31 @@ impl PathBuf {
     }
 
     /// Allocates an empty `PathBuf`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::path::PathBuf;
+    ///
+    /// let path = PathBuf::new();
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn new() -> PathBuf {
         PathBuf { inner: OsString::new() }
     }
 
-    /// Coerces to a `Path` slice.
+    /// Coerces to a [`Path`] slice.
+    ///
+    /// [`Path`]: struct.Path.html
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::path::{Path, PathBuf};
+    ///
+    /// let p = PathBuf::from("/test");
+    /// assert_eq!(Path::new("/test"), p.as_path());
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn as_path(&self) -> &Path {
         self
@@ -1091,10 +1115,26 @@ impl PathBuf {
         self.inner.push(path);
     }
 
-    /// Truncate `self` to `self.parent()`.
+    /// Truncate `self` to [`self.parent()`].
     ///
-    /// Returns false and does nothing if `self.file_name()` is `None`.
+    /// Returns false and does nothing if [`self.file_name()`] is `None`.
     /// Otherwise, returns `true`.
+    ///
+    /// [`self.parent()`]: struct.PathBuf.html#method.parent
+    /// [`self.file_name()`]: struct.PathBuf.html#method.file_name
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::path::{Path, PathBuf};
+    ///
+    /// let mut p = PathBuf::from("/test/test.rs");
+    ///
+    /// p.pop();
+    /// assert_eq!(Path::new("/test"), p.as_path());
+    /// p.pop();
+    /// assert_eq!(Path::new("/"), p.as_path());
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn pop(&mut self) -> bool {
         match self.parent().map(|p| p.as_u8_slice().len()) {
@@ -1106,11 +1146,13 @@ impl PathBuf {
         }
     }
 
-    /// Updates `self.file_name()` to `file_name`.
+    /// Updates [`self.file_name()`] to `file_name`.
     ///
     /// If `self.file_name()` was `None`, this is equivalent to pushing
     /// `file_name`.
     ///
+    /// [`self.file_name()`]: struct.PathBuf.html#method.file_name
+    ///
     /// # Examples
     ///
     /// ```
@@ -1137,12 +1179,29 @@ impl PathBuf {
         self.push(file_name);
     }
 
-    /// Updates `self.extension()` to `extension`.
+    /// Updates [`self.extension()`] to `extension`.
+    ///
+    /// If [`self.file_name()`] is `None`, does nothing and returns `false`.
+    ///
+    /// Otherwise, returns `true`; if [`self.extension()`] is `None`, the
+    /// extension is added; otherwise it is replaced.
+    ///
+    /// [`self.file_name()`]: struct.PathBuf.html#method.file_name
+    /// [`self.extension()`]: struct.PathBuf.html#method.extension
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::path::{Path, PathBuf};
     ///
-    /// If `self.file_name()` is `None`, does nothing and returns `false`.
+    /// let mut p = PathBuf::from("/feel/the");
     ///
-    /// Otherwise, returns `true`; if `self.extension()` is `None`, the extension
-    /// is added; otherwise it is replaced.
+    /// p.set_extension("force");
+    /// assert_eq!(Path::new("/feel/the.force"), p.as_path());
+    ///
+    /// p.set_extension("dark_side");
+    /// assert_eq!(Path::new("/feel/the.dark_side"), p.as_path());
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn set_extension<S: AsRef<OsStr>>(&mut self, extension: S) -> bool {
         self._set_extension(extension.as_ref())
@@ -1167,7 +1226,18 @@ impl PathBuf {
         true
     }
 
-    /// Consumes the `PathBuf`, yielding its internal `OsString` storage.
+    /// Consumes the `PathBuf`, yielding its internal [`OsString`] storage.
+    ///
+    /// [`OsString`]: ../ffi/struct.OsString.html
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::path::PathBuf;
+    ///
+    /// let p = PathBuf::from("/the/head");
+    /// let os_str = p.into_os_string();
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn into_os_string(self) -> OsString {
         self.inner
@@ -1305,7 +1375,7 @@ impl Into<OsString> for PathBuf {
     }
 }
 
-/// A slice of a path (akin to `str`).
+/// A slice of a path (akin to [`str`]).
 ///
 /// This type supports a number of operations for inspecting a path, including
 /// breaking the path into its components (separated by `/` or `\`, depending on
@@ -1314,7 +1384,10 @@ impl Into<OsString> for PathBuf {
 /// the module documentation.
 ///
 /// This is an *unsized* type, meaning that it must always be used behind a
-/// pointer like `&` or `Box`.
+/// pointer like `&` or [`Box`].
+///
+/// [`str`]: ../primitive.str.html
+/// [`Box`]: ../boxed/struct.Box.html
 ///
 /// # Examples
 ///
@@ -1376,7 +1449,9 @@ impl Path {
         unsafe { mem::transmute(s.as_ref()) }
     }
 
-    /// Yields the underlying `OsStr` slice.
+    /// Yields the underlying [`OsStr`] slice.
+    ///
+    /// [`OsStr`]: ../ffi/struct.OsStr.html
     ///
     /// # Examples
     ///
@@ -1391,10 +1466,12 @@ impl Path {
         &self.inner
     }
 
-    /// Yields a `&str` slice if the `Path` is valid unicode.
+    /// Yields a [`&str`] slice if the `Path` is valid unicode.
     ///
     /// This conversion may entail doing a check for UTF-8 validity.
     ///
+    /// [`&str`]: ../primitive.str.html
+    ///
     /// # Examples
     ///
     /// ```
@@ -1408,10 +1485,12 @@ impl Path {
         self.inner.to_str()
     }
 
-    /// Converts a `Path` to a `Cow<str>`.
+    /// Converts a `Path` to a [`Cow<str>`].
     ///
     /// Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.
     ///
+    /// [`Cow<str>`]: ../borrow/enum.Cow.html
+    ///
     /// # Examples
     ///
     /// ```
@@ -1425,7 +1504,9 @@ impl Path {
         self.inner.to_string_lossy()
     }
 
-    /// Converts a `Path` to an owned `PathBuf`.
+    /// Converts a `Path` to an owned [`PathBuf`].
+    ///
+    /// [`PathBuf`]: struct.PathBuf.html
     ///
     /// # Examples
     ///
@@ -1573,6 +1654,18 @@ impl Path {
     ///
     /// If `base` is not a prefix of `self` (i.e. `starts_with`
     /// returns `false`), returns `Err`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::path::Path;
+    ///
+    /// let path = Path::new("/test/haha/foo.txt");
+    ///
+    /// assert_eq!(path.strip_prefix("/test"), Ok(Path::new("haha/foo.txt")));
+    /// assert_eq!(path.strip_prefix("test").is_ok(), false);
+    /// assert_eq!(path.strip_prefix("/haha").is_ok(), false);
+    /// ```
     #[stable(since = "1.7.0", feature = "path_strip_prefix")]
     pub fn strip_prefix<'a, P: ?Sized>(&'a self, base: &'a P)
                                        -> Result<&'a Path, StripPrefixError>
@@ -1634,7 +1727,9 @@ impl Path {
         iter_after(self.components().rev(), child.components().rev()).is_some()
     }
 
-    /// Extracts the stem (non-extension) portion of `self.file_name()`.
+    /// Extracts the stem (non-extension) portion of [`self.file_name()`].
+    ///
+    /// [`self.file_name()`]: struct.Path.html#method.file_name
     ///
     /// The stem is:
     ///
@@ -1657,7 +1752,9 @@ impl Path {
         self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.or(after))
     }
 
-    /// Extracts the extension of `self.file_name()`, if possible.
+    /// Extracts the extension of [`self.file_name()`], if possible.
+    ///
+    /// [`self.file_name()`]: struct.Path.html#method.file_name
     ///
     /// The extension is:
     ///
@@ -1680,9 +1777,12 @@ impl Path {
         self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.and(after))
     }
 
-    /// Creates an owned `PathBuf` with `path` adjoined to `self`.
+    /// Creates an owned [`PathBuf`] with `path` adjoined to `self`.
+    ///
+    /// See [`PathBuf::push`] for more details on what it means to adjoin a path.
     ///
-    /// See `PathBuf::push` for more details on what it means to adjoin a path.
+    /// [`PathBuf`]: struct.PathBuf.html
+    /// [`PathBuf::push`]: struct.PathBuf.html#method.push
     ///
     /// # Examples
     ///
@@ -1702,9 +1802,12 @@ impl Path {
         buf
     }
 
-    /// Creates an owned `PathBuf` like `self` but with the given file name.
+    /// Creates an owned [`PathBuf`] like `self` but with the given file name.
     ///
-    /// See `PathBuf::set_file_name` for more details.
+    /// See [`PathBuf::set_file_name`] for more details.
+    ///
+    /// [`PathBuf`]: struct.PathBuf.html
+    /// [`PathBuf::set_file_name`]: struct.PathBuf.html#method.set_file_name
     ///
     /// # Examples
     ///
@@ -1725,9 +1828,12 @@ impl Path {
         buf
     }
 
-    /// Creates an owned `PathBuf` like `self` but with the given extension.
+    /// Creates an owned [`PathBuf`] like `self` but with the given extension.
+    ///
+    /// See [`PathBuf::set_extension`] for more details.
     ///
-    /// See `PathBuf::set_extension` for more details.
+    /// [`PathBuf`]: struct.PathBuf.html
+    /// [`PathBuf::set_extension`]: struct.PathBuf.html#method.set_extension
     ///
     /// # Examples
     ///
@@ -1775,7 +1881,9 @@ impl Path {
         }
     }
 
-    /// Produce an iterator over the path's components viewed as `OsStr` slices.
+    /// Produce an iterator over the path's components viewed as [`OsStr`] slices.
+    ///
+    /// [`OsStr`]: ../ffi/struct.OsStr.html
     ///
     /// # Examples
     ///
@@ -1794,9 +1902,11 @@ impl Path {
         Iter { inner: self.components() }
     }
 
-    /// Returns an object that implements `Display` for safely printing paths
+    /// Returns an object that implements [`Display`] for safely printing paths
     /// that may contain non-Unicode data.
     ///
+    /// [`Display`]: fmt/trait.Display.html
+    ///
     /// # Examples
     ///
     /// ```
@@ -1858,11 +1968,13 @@ impl Path {
 
     /// Returns an iterator over the entries within a directory.
     ///
-    /// The iterator will yield instances of `io::Result<DirEntry>`. New errors may
-    /// be encountered after an iterator is initially constructed.
+    /// The iterator will yield instances of [`io::Result<`][`DirEntry`]`>`. New
+    /// errors may be encountered after an iterator is initially constructed.
     ///
     /// This is an alias to [`fs::read_dir`].
     ///
+    /// [`io::Result<`]: ../io/type.Result.html
+    /// [`DirEntry`]: ../fs/struct.DirEntry.html
     /// [`fs::read_dir`]: ../fs/fn.read_dir.html
     #[stable(feature = "path_ext", since = "1.5.0")]
     pub fn read_dir(&self) -> io::Result<fs::ReadDir> {
diff --git a/src/test/compile-fail/E0389.rs b/src/test/compile-fail/E0389.rs
index 445831bf8d7f7..584dfd5fa440c 100644
--- a/src/test/compile-fail/E0389.rs
+++ b/src/test/compile-fail/E0389.rs
@@ -16,5 +16,6 @@ fn main() {
     let mut fancy = FancyNum{ num: 5 };
     let fancy_ref = &(&mut fancy);
     fancy_ref.num = 6; //~ ERROR E0389
+                       //~^ NOTE assignment into an immutable reference
     println!("{}", fancy_ref.num);
 }