Rollup merge of #23297 - steveklabnik:examples, r=huonw

 This brings comments in line with https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md#using-markdown

12 files changed, 89 insertions, 89 deletions

diff --git a/src/libcore/finally.rs b/src/libcore/finally.rs
index 562a597cccf..74806e52d26 100644
--- a/src/libcore/finally.rs
+++ b/src/libcore/finally.rs
@@ -16,7 +16,7 @@
 //! "finally" case. For advanced cases, the `try_finally` function can
 //! also be used. See that function for more details.
 //!
-//! # Example
+//! # Examples
 //!
 //! ```
 //! # #![feature(unboxed_closures)]
@@ -67,7 +67,7 @@ impl<T, F> Finally<T> for F where F: FnMut() -> T {
 /// function could have panicked at any point, so the values of the shared
 /// state may be inconsistent.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::finally::try_finally;
diff --git a/src/libcore/fmt/num.rs b/src/libcore/fmt/num.rs
index b3f2302bb3e..fe22ee60da6 100644
--- a/src/libcore/fmt/num.rs
+++ b/src/libcore/fmt/num.rs
@@ -143,7 +143,7 @@ pub struct RadixFmt<T, R>(T, R);
 
 /// Constructs a radix formatter in the range of `2..36`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::fmt::radix;
diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs
index d5e891a156e..74bc87ecbf3 100644
--- a/src/libcore/iter.rs
+++ b/src/libcore/iter.rs
@@ -2296,7 +2296,7 @@ impl<I: RandomAccessIterator, F> RandomAccessIterator for Inspect<I, F>
 
 /// An iterator that passes mutable state to a closure and yields the result.
 ///
-/// # Example: The Fibonacci Sequence
+/// # Examples
 ///
 /// An iterator that yields sequential Fibonacci numbers, and stops on overflow.
 ///
diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs
index c2860d43511..6575bac501f 100644
--- a/src/libcore/macros.rs
+++ b/src/libcore/macros.rs
@@ -33,7 +33,7 @@ macro_rules! panic {
 /// This will invoke the `panic!` macro if the provided expression cannot be
 /// evaluated to `true` at runtime.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// // the panic message for these assertions is the stringified value of the
@@ -71,7 +71,7 @@ macro_rules! assert {
 ///
 /// On panic, this macro will print the values of the expressions.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// let a = 3;
@@ -107,7 +107,7 @@ macro_rules! assert_eq {
 /// expensive to be present in a release build but may be helpful during
 /// development.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// // the panic message for these assertions is the stringified value of the
@@ -142,7 +142,7 @@ macro_rules! debug_assert {
 /// expensive to be present in a release build but may be helpful during
 /// development.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// let a = 3;
@@ -172,7 +172,7 @@ macro_rules! try {
 /// Use the `format!` syntax to write data into a buffer of type `&mut Writer`.
 /// See `std::fmt` for more information.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// # #![allow(unused_must_use)]
diff --git a/src/libcore/marker.rs b/src/libcore/marker.rs
index fe53ea1f0af..d596a06709c 100644
--- a/src/libcore/marker.rs
+++ b/src/libcore/marker.rs
@@ -288,7 +288,7 @@ impl<T:?Sized> MarkerTrait for T { }
 /// can extend `MarkerTrait`, which is equivalent to
 /// `PhantomFn<Self>`.
 ///
-/// # Example
+/// # Examples
 ///
 /// As an example, consider a trait with no methods like `Even`, meant
 /// to represent types that are "even":
diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs
index 752eca797bd..6170092c8d1 100644
--- a/src/libcore/num/mod.rs
+++ b/src/libcore/num/mod.rs
@@ -82,7 +82,7 @@ pub trait Int
 
     /// Returns the number of ones in the binary representation of `self`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -97,7 +97,7 @@ pub trait Int
 
     /// Returns the number of zeros in the binary representation of `self`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -116,7 +116,7 @@ pub trait Int
     /// Returns the number of leading zeros in the binary representation
     /// of `self`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -132,7 +132,7 @@ pub trait Int
     /// Returns the number of trailing zeros in the binary representation
     /// of `self`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -148,7 +148,7 @@ pub trait Int
     /// Shifts the bits to the left by a specified amount amount, `n`, wrapping
     /// the truncated bits to the end of the resulting integer.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -165,7 +165,7 @@ pub trait Int
     /// Shifts the bits to the right by a specified amount amount, `n`, wrapping
     /// the truncated bits to the beginning of the resulting integer.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -181,7 +181,7 @@ pub trait Int
 
     /// Reverses the byte order of the integer.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -198,7 +198,7 @@ pub trait Int
     ///
     /// On big endian this is a no-op. On little endian the bytes are swapped.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -221,7 +221,7 @@ pub trait Int
     ///
     /// On little endian this is a no-op. On big endian the bytes are swapped.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -244,7 +244,7 @@ pub trait Int
     ///
     /// On big endian this is a no-op. On little endian the bytes are swapped.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -267,7 +267,7 @@ pub trait Int
     ///
     /// On little endian this is a no-op. On big endian the bytes are swapped.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -289,7 +289,7 @@ pub trait Int
     /// Checked integer addition. Computes `self + other`, returning `None` if
     /// overflow occurred.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -303,7 +303,7 @@ pub trait Int
     /// Checked integer subtraction. Computes `self - other`, returning `None`
     /// if underflow occurred.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -317,7 +317,7 @@ pub trait Int
     /// Checked integer multiplication. Computes `self * other`, returning
     /// `None` if underflow or overflow occurred.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -331,7 +331,7 @@ pub trait Int
     /// Checked integer division. Computes `self / other`, returning `None` if
     /// `other == 0` or the operation results in underflow or overflow.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -369,7 +369,7 @@ pub trait Int
 
     /// Raises self to the power of `exp`, using exponentiation by squaring.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -1273,7 +1273,7 @@ impl_from_primitive! { f64, to_f64 }
 
 /// Cast from one machine scalar to another.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::num;
diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs
index 4116d8be9fb..077b44f2dd2 100644
--- a/src/libcore/ops.rs
+++ b/src/libcore/ops.rs
@@ -27,7 +27,7 @@
 //! idea to have both `T` and `&T` implement the traits `Add<T>` and `Add<&T>`
 //! so that generic code can be written without unnecessary cloning.
 //!
-//! # Example
+//! # Examples
 //!
 //! This example creates a `Point` struct that implements `Add` and `Sub`, and then
 //! demonstrates adding and subtracting two `Point`s.
@@ -73,7 +73,7 @@ use fmt;
 /// The `Drop` trait is used to run some code when a value goes out of scope. This
 /// is sometimes called a 'destructor'.
 ///
-/// # Example
+/// # Examples
 ///
 /// A trivial implementation of `Drop`. The `drop` method is called when `_x` goes
 /// out of scope, and therefore `main` prints `Dropping!`.
@@ -157,7 +157,7 @@ macro_rules! forward_ref_binop {
 
 /// The `Add` trait is used to specify the functionality of `+`.
 ///
-/// # Example
+/// # Examples
 ///
 /// A trivial implementation of `Add`. When `Foo + Foo` happens, it ends up
 /// calling `add`, and therefore, `main` prints `Adding!`.
@@ -211,7 +211,7 @@ add_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 
 /// The `Sub` trait is used to specify the functionality of `-`.
 ///
-/// # Example
+/// # Examples
 ///
 /// A trivial implementation of `Sub`. When `Foo - Foo` happens, it ends up
 /// calling `sub`, and therefore, `main` prints `Subtracting!`.
@@ -265,7 +265,7 @@ sub_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 
 /// The `Mul` trait is used to specify the functionality of `*`.
 ///
-/// # Example
+/// # Examples
 ///
 /// A trivial implementation of `Mul`. When `Foo * Foo` happens, it ends up
 /// calling `mul`, and therefore, `main` prints `Multiplying!`.
@@ -319,7 +319,7 @@ mul_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 
 /// The `Div` trait is used to specify the functionality of `/`.
 ///
-/// # Example
+/// # Examples
 ///
 /// A trivial implementation of `Div`. When `Foo / Foo` happens, it ends up
 /// calling `div`, and therefore, `main` prints `Dividing!`.
@@ -373,7 +373,7 @@ div_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 
 /// The `Rem` trait is used to specify the functionality of `%`.
 ///
-/// # Example
+/// # Examples
 ///
 /// A trivial implementation of `Rem`. When `Foo % Foo` happens, it ends up
 /// calling `rem`, and therefore, `main` prints `Remainder-ing!`.
@@ -446,7 +446,7 @@ rem_float_impl! { f64, fmod }
 
 /// The `Neg` trait is used to specify the functionality of unary `-`.
 ///
-/// # Example
+/// # Examples
 ///
 /// A trivial implementation of `Neg`. When `-Foo` happens, it ends up calling
 /// `neg`, and therefore, `main` prints `Negating!`.
@@ -523,7 +523,7 @@ neg_uint_impl! { u64, i64 }
 
 /// The `Not` trait is used to specify the functionality of unary `!`.
 ///
-/// # Example
+/// # Examples
 ///
 /// A trivial implementation of `Not`. When `!Foo` happens, it ends up calling
 /// `not`, and therefore, `main` prints `Not-ing!`.
@@ -577,7 +577,7 @@ not_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 
 /// The `BitAnd` trait is used to specify the functionality of `&`.
 ///
-/// # Example
+/// # Examples
 ///
 /// A trivial implementation of `BitAnd`. When `Foo & Foo` happens, it ends up
 /// calling `bitand`, and therefore, `main` prints `Bitwise And-ing!`.
@@ -631,7 +631,7 @@ bitand_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 
 /// The `BitOr` trait is used to specify the functionality of `|`.
 ///
-/// # Example
+/// # Examples
 ///
 /// A trivial implementation of `BitOr`. When `Foo | Foo` happens, it ends up
 /// calling `bitor`, and therefore, `main` prints `Bitwise Or-ing!`.
@@ -685,7 +685,7 @@ bitor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 
 /// The `BitXor` trait is used to specify the functionality of `^`.
 ///
-/// # Example
+/// # Examples
 ///
 /// A trivial implementation of `BitXor`. When `Foo ^ Foo` happens, it ends up
 /// calling `bitxor`, and therefore, `main` prints `Bitwise Xor-ing!`.
@@ -739,7 +739,7 @@ bitxor_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 
 /// The `Shl` trait is used to specify the functionality of `<<`.
 ///
-/// # Example
+/// # Examples
 ///
 /// A trivial implementation of `Shl`. When `Foo << Foo` happens, it ends up
 /// calling `shl`, and therefore, `main` prints `Shifting left!`.
@@ -811,7 +811,7 @@ shl_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 
 /// The `Shr` trait is used to specify the functionality of `>>`.
 ///
-/// # Example
+/// # Examples
 ///
 /// A trivial implementation of `Shr`. When `Foo >> Foo` happens, it ends up
 /// calling `shr`, and therefore, `main` prints `Shifting right!`.
@@ -883,7 +883,7 @@ shr_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 /// The `Index` trait is used to specify the functionality of indexing operations
 /// like `arr[idx]` when used in an immutable context.
 ///
-/// # Example
+/// # Examples
 ///
 /// A trivial implementation of `Index`. When `Foo[Bar]` happens, it ends up
 /// calling `index`, and therefore, `main` prints `Indexing!`.
@@ -924,7 +924,7 @@ pub trait Index<Idx: ?Sized> {
 /// The `IndexMut` trait is used to specify the functionality of indexing
 /// operations like `arr[idx]`, when used in a mutable context.
 ///
-/// # Example
+/// # Examples
 ///
 /// A trivial implementation of `IndexMut`. When `Foo[Bar]` happens, it ends up
 /// calling `index_mut`, and therefore, `main` prints `Indexing!`.
@@ -1033,7 +1033,7 @@ impl<Idx: fmt::Debug> fmt::Debug for RangeTo<Idx> {
 /// The `Deref` trait is used to specify the functionality of dereferencing
 /// operations like `*v`.
 ///
-/// # Example
+/// # Examples
 ///
 /// A struct with a single field which is accessible via dereferencing the
 /// struct.
@@ -1087,7 +1087,7 @@ impl<'a, T: ?Sized> Deref for &'a mut T {
 /// The `DerefMut` trait is used to specify the functionality of dereferencing
 /// mutably like `*v = 1;`
 ///
-/// # Example
+/// # Examples
 ///
 /// A struct with a single field which is modifiable via dereferencing the
 /// struct.
diff --git a/src/libcore/option.rs b/src/libcore/option.rs
index 5343cdaaf08..2dd8bf67220 100644
--- a/src/libcore/option.rs
+++ b/src/libcore/option.rs
@@ -185,7 +185,7 @@ impl<T> Option<T> {
 
     /// Returns `true` if the option is a `Some` value
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x: Option<u32> = Some(2);
@@ -205,7 +205,7 @@ impl<T> Option<T> {
 
     /// Returns `true` if the option is a `None` value
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x: Option<u32> = Some(2);
@@ -226,7 +226,7 @@ impl<T> Option<T> {
 
     /// Convert from `Option<T>` to `Option<&T>`
     ///
-    /// # Example
+    /// # Examples
     ///
     /// Convert an `Option<String>` into an `Option<usize>`, preserving the original.
     /// The `map` method takes the `self` argument by value, consuming the original,
@@ -251,7 +251,7 @@ impl<T> Option<T> {
 
     /// Convert from `Option<T>` to `Option<&mut T>`
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let mut x = Some(2);
@@ -272,7 +272,7 @@ impl<T> Option<T> {
 
     /// Convert from `Option<T>` to `&mut [T]` (without copying)
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let mut x = Some("Diamonds");
@@ -311,7 +311,7 @@ impl<T> Option<T> {
     /// Panics if the value is a `None` with a custom panic message provided by
     /// `msg`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x = Some("value");
@@ -343,7 +343,7 @@ impl<T> Option<T> {
     /// Instead, prefer to use pattern matching and handle the `None`
     /// case explicitly.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x = Some("air");
@@ -365,7 +365,7 @@ impl<T> Option<T> {
 
     /// Returns the contained value or a default.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// assert_eq!(Some("car").unwrap_or("bike"), "car");
@@ -382,7 +382,7 @@ impl<T> Option<T> {
 
     /// Returns the contained value or computes it from a closure.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let k = 10;
@@ -404,7 +404,7 @@ impl<T> Option<T> {
 
     /// Maps an `Option<T>` to `Option<U>` by applying a function to a contained value
     ///
-    /// # Example
+    /// # Examples
     ///
     /// Convert an `Option<String>` into an `Option<usize>`, consuming the original:
     ///
@@ -424,7 +424,7 @@ impl<T> Option<T> {
 
     /// Applies a function to the contained value or returns a default.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x = Some("foo");
@@ -444,7 +444,7 @@ impl<T> Option<T> {
 
     /// Applies a function to the contained value or computes a default.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let k = 21;
@@ -467,7 +467,7 @@ impl<T> Option<T> {
     /// Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to
     /// `Ok(v)` and `None` to `Err(err)`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x = Some("foo");
@@ -488,7 +488,7 @@ impl<T> Option<T> {
     /// Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to
     /// `Ok(v)` and `None` to `Err(err())`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x = Some("foo");
@@ -512,7 +512,7 @@ impl<T> Option<T> {
 
     /// Returns an iterator over the possibly contained value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x = Some(4);
@@ -529,7 +529,7 @@ impl<T> Option<T> {
 
     /// Returns a mutable iterator over the possibly contained value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let mut x = Some(4);
@@ -551,7 +551,7 @@ impl<T> Option<T> {
 
     /// Returns a consuming iterator over the possibly contained value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x = Some("string");
@@ -574,7 +574,7 @@ impl<T> Option<T> {
 
     /// Returns `None` if the option is `None`, otherwise returns `optb`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x = Some(2);
@@ -607,7 +607,7 @@ impl<T> Option<T> {
     ///
     /// Some languages call this operation flatmap.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// fn sq(x: u32) -> Option<u32> { Some(x * x) }
@@ -629,7 +629,7 @@ impl<T> Option<T> {
 
     /// Returns the option if it contains a value, otherwise returns `optb`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x = Some(2);
@@ -660,7 +660,7 @@ impl<T> Option<T> {
     /// Returns the option if it contains a value, otherwise calls `f` and
     /// returns the result.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// fn nobody() -> Option<&'static str> { None }
@@ -685,7 +685,7 @@ impl<T> Option<T> {
 
     /// Takes the value out of the option, leaving a `None` in its place.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let mut x = Some(2);
@@ -720,7 +720,7 @@ impl<T: Default> Option<T> {
     /// value, otherwise if `None`, returns the default value for that
     /// type.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// Convert a string to an integer, turning poorly-formed strings
     /// into 0 (the default value for integers). `parse` converts
diff --git a/src/libcore/result.rs b/src/libcore/result.rs
index 6c3afdf8849..9fba9a4d8ec 100644
--- a/src/libcore/result.rs
+++ b/src/libcore/result.rs
@@ -265,7 +265,7 @@ impl<T, E> Result<T, E> {
 
     /// Returns true if the result is `Ok`
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x: Result<int, &str> = Ok(-3);
@@ -285,7 +285,7 @@ impl<T, E> Result<T, E> {
 
     /// Returns true if the result is `Err`
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x: Result<int, &str> = Ok(-3);
@@ -309,7 +309,7 @@ impl<T, E> Result<T, E> {
     /// Converts `self` into an `Option<T>`, consuming `self`,
     /// and discarding the error, if any.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x: Result<u32, &str> = Ok(2);
@@ -332,7 +332,7 @@ impl<T, E> Result<T, E> {
     /// Converts `self` into an `Option<E>`, consuming `self`,
     /// and discarding the value, if any.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x: Result<u32, &str> = Ok(2);
@@ -440,7 +440,7 @@ impl<T, E> Result<T, E> {
     ///
     /// This function can be used to compose the results of two functions.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// Sum the lines of a buffer by mapping strings to numbers,
     /// ignoring I/O and parse errors:
@@ -479,7 +479,7 @@ impl<T, E> Result<T, E> {
     /// This function can be used to pass through a successful result while handling
     /// an error.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// fn stringify(x: u32) -> String { format!("error code: {}", x) }
@@ -505,7 +505,7 @@ impl<T, E> Result<T, E> {
 
     /// Returns an iterator over the possibly contained value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x: Result<u32, &str> = Ok(7);
@@ -522,7 +522,7 @@ impl<T, E> Result<T, E> {
 
     /// Returns a mutable iterator over the possibly contained value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let mut x: Result<u32, &str> = Ok(7);
@@ -543,7 +543,7 @@ impl<T, E> Result<T, E> {
 
     /// Returns a consuming iterator over the possibly contained value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x: Result<u32, &str> = Ok(5);
@@ -566,7 +566,7 @@ impl<T, E> Result<T, E> {
 
     /// Returns `res` if the result is `Ok`, otherwise returns the `Err` value of `self`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x: Result<u32, &str> = Ok(2);
@@ -598,7 +598,7 @@ impl<T, E> Result<T, E> {
     ///
     /// This function can be used for control flow based on result values.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// fn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }
@@ -620,7 +620,7 @@ impl<T, E> Result<T, E> {
 
     /// Returns `res` if the result is `Err`, otherwise returns the `Ok` value of `self`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x: Result<u32, &str> = Ok(2);
@@ -652,7 +652,7 @@ impl<T, E> Result<T, E> {
     ///
     /// This function can be used for control flow based on result values.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// fn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }
@@ -675,7 +675,7 @@ impl<T, E> Result<T, E> {
     /// Unwraps a result, yielding the content of an `Ok`.
     /// Else it returns `optb`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let optb = 2;
@@ -697,7 +697,7 @@ impl<T, E> Result<T, E> {
     /// Unwraps a result, yielding the content of an `Ok`.
     /// If the value is an `Err` then it calls `op` with its value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// fn count(x: &str) -> usize { x.len() }
@@ -724,7 +724,7 @@ impl<T, E: fmt::Debug> Result<T, E> {
     /// Panics if the value is an `Err`, with a custom panic message provided
     /// by the `Err`'s value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x: Result<u32, &str> = Ok(2);
@@ -755,7 +755,7 @@ impl<T: fmt::Debug, E> Result<T, E> {
     /// Panics if the value is an `Ok`, with a custom panic message provided
     /// by the `Ok`'s value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```{.should_fail}
     /// let x: Result<u32, &str> = Ok(2);
diff --git a/src/libcore/slice.rs b/src/libcore/slice.rs
index 1f58d775354..a8282e5701e 100644
--- a/src/libcore/slice.rs
+++ b/src/libcore/slice.rs
@@ -1433,7 +1433,7 @@ pub fn mut_ref_slice<'a, A>(s: &'a mut A) -> &'a mut [A] {
 /// function taking the lifetime of a host value for the slice, or by explicit
 /// annotation.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::slice;
@@ -1476,7 +1476,7 @@ pub unsafe fn from_raw_parts_mut<'a, T>(p: *mut T, len: usize) -> &'a mut [T] {
 /// valid for `len` elements, nor whether the lifetime provided is a suitable
 /// lifetime for the returned slice.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::slice;
diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs
index a5ade2ae2a5..6f72890d96f 100644
--- a/src/libcore/str/mod.rs
+++ b/src/libcore/str/mod.rs
@@ -1183,7 +1183,7 @@ mod traits {
     /// Panics when `begin` and `end` do not point to valid characters
     /// or point beyond the last character of the string.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let s = "Löwe 老虎 Léopard";
diff --git a/src/libcore/str/pattern.rs b/src/libcore/str/pattern.rs
index 1f669c66eb1..9eeb9b869ce 100644
--- a/src/libcore/str/pattern.rs
+++ b/src/libcore/str/pattern.rs
@@ -215,7 +215,7 @@ pub unsafe trait ReverseSearcher<'a>: Searcher<'a> {
 ///   the two ends of a range of values, that is they
 ///   can not "walk past each other".
 ///
-/// # Example
+/// # Examples
 ///
 /// `char::Searcher` is a `DoubleEndedSearcher` because searching for a
 /// `char` only requires looking at one at a time, which behaves the same