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

src/doc/trpl/comments.md

@@ -28,7 +28,7 @@ The other kind of comment is a doc comment. Doc comments use `///` instead of
 ///
 /// * `name` - The name of the person you'd like to greet.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// let name = "Steve";

src/liballoc/arc.rs

@@ -88,7 +88,7 @@
 
 /// An atomically reference counted wrapper for shared state.
 ///
-/// # Example
+/// # Examples
 ///
 /// In this example, a large vector of floats is shared between several tasks.
 /// With simple pipes, without `Arc`, a copy would have to be made for each

src/liballoc/boxed.rs

@@ -133,7 +133,7 @@ pub unsafe fn from_raw(raw: *mut T) -> Self {
 /// automatically managed that may lead to memory or other resource
 /// leak.
 ///
-/// # Example
+/// # Examples
 /// ```
 /// use std::boxed;
 ///

src/liballoc/rc.rs

@@ -264,7 +264,7 @@ pub fn is_unique<T>(rc: &Rc<T>) -> bool {
 ///
 /// If the `Rc<T>` is not unique, an `Err` is returned with the same `Rc<T>`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::rc::{self, Rc};
@@ -298,7 +298,7 @@ pub fn try_unwrap<T>(rc: Rc<T>) -> Result<T, Rc<T>> {
 ///
 /// Returns `None` if the `Rc<T>` is not unique.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::rc::{self, Rc};

src/libcollections/borrow.rs

@@ -127,7 +127,7 @@ fn to_owned(&self) -> T { self.clone() }
 /// is desired, `to_mut` will obtain a mutable references to an owned
 /// value, cloning if necessary.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::borrow::Cow;

src/libcollections/btree/map.rs

@@ -1177,7 +1177,7 @@ pub fn remove(self) -> V {
 impl<K, V> BTreeMap<K, V> {
     /// Gets an iterator over the entries of the map.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::BTreeMap;

src/libcollections/fmt.rs

@@ -420,7 +420,7 @@
 ///
 ///   * args - a structure of arguments generated via the `format_args!` macro.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::fmt;

src/libcollections/macros.rs

@@ -48,7 +48,7 @@ macro_rules! vec {
 /// Use the syntax described in `std::fmt` to create a value of type `String`.
 /// See `std::fmt` for more information.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// format!("test");

src/libcollections/slice.rs

@@ -277,7 +277,7 @@ fn rsplitn<F>(&self, n: usize, pred: F) -> RSplitN<Self::Item, F>
     ///
     /// Panics if `size` is 0.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// Print the adjacent pairs of a slice (i.e. `[1,2]`, `[2,3]`,
     /// `[3,4]`):
@@ -300,7 +300,7 @@ fn rsplitn<F>(&self, n: usize, pred: F) -> RSplitN<Self::Item, F>
     ///
     /// Panics if `size` is 0.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// Print the slice two elements at a time (i.e. `[1,2]`,
     /// `[3,4]`, `[5]`):
@@ -390,7 +390,7 @@ fn rsplitn<F>(&self, n: usize, pred: F) -> RSplitN<Self::Item, F>
     /// `Err` is returned, containing the index where a matching
     /// element could be inserted while maintaining sorted order.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// Looks up a series of four elements. The first is found, with a
     /// uniquely determined position; the second and third are not
@@ -416,7 +416,7 @@ fn binary_search_by<F>(&self, f: F) -> Result<usize, usize> where
 
     /// Return the number of elements in the slice
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let a = [1, 2, 3];
@@ -427,7 +427,7 @@ fn binary_search_by<F>(&self, f: F) -> Result<usize, usize> where
 
     /// Returns true if the slice has a length of 0
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let a = [1, 2, 3];
@@ -529,7 +529,7 @@ fn rsplitn_mut<F>(&mut self,  n: usize, pred: F) -> RSplitNMut<Self::Item, F>
     ///
     /// Panics if `a` or `b` are out of bounds.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let mut v = ["a", "b", "c", "d"];
@@ -549,7 +549,7 @@ fn rsplitn_mut<F>(&mut self,  n: usize, pred: F) -> RSplitNMut<Self::Item, F>
     ///
     /// Panics if `mid > len`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let mut v = [1, 2, 3, 4, 5, 6];
@@ -578,7 +578,7 @@ fn rsplitn_mut<F>(&mut self,  n: usize, pred: F) -> RSplitNMut<Self::Item, F>
 
     /// Reverse the order of elements in a slice, in place.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let mut v = [1, 2, 3];
@@ -638,7 +638,7 @@ fn rsplitn_mut<F>(&mut self,  n: usize, pred: F) -> RSplitNMut<Self::Item, F>
     /// shorter of `self.len()` and `src.len()`). Returns the number
     /// of elements copied.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let mut dst = [0, 0, 0];
@@ -676,7 +676,7 @@ fn rsplitn_mut<F>(&mut self,  n: usize, pred: F) -> RSplitNMut<Self::Item, F>
     /// `Err` is returned, containing the index where a matching
     /// element could be inserted while maintaining sorted order.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// Looks up a series of four elements. The first is found, with a
     /// uniquely determined position; the second and third are not
@@ -707,7 +707,7 @@ fn binary_search_elem(&self, x: &Self::Item) -> Result<usize, usize> where Self:
     /// Returns `true` if successful and `false` if the slice is at the
     /// last-ordered permutation.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let v: &mut [_] = &mut [0, 1, 2];
@@ -727,7 +727,7 @@ fn binary_search_elem(&self, x: &Self::Item) -> Result<usize, usize> where Self:
     /// Returns `true` if successful and `false` if the slice is at the
     /// first-ordered permutation.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let v: &mut [_] = &mut [1, 0, 2];

src/libcollections/str.rs

@@ -1377,7 +1377,7 @@ fn is_empty(&self) -> bool {
     ///
     /// Will return `Err` if it's not possible to parse `self` into the type.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// assert_eq!("4".parse::<u32>(), Ok(4));

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 @@ fn finally<G>(&mut self, mut dtor: G) -> T where G: FnMut() {
 /// function could have panicked at any point, so the values of the shared
 /// state may be inconsistent.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::finally::try_finally;

src/libcore/fmt/num.rs

@@ -143,7 +143,7 @@ fn digit(&self, x: u8) -> u8 {
 
 /// Constructs a radix formatter in the range of `2..36`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::fmt::radix;

src/libcore/iter.rs

@@ -2296,7 +2296,7 @@ fn idx(&mut self, index: usize) -> Option<I::Item> {
 
 /// 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.
 ///

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)]

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":

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 @@ fn count_zeros(self) -> u32 {
     /// Returns the number of leading zeros in the binary representation
     /// of `self`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -132,7 +132,7 @@ fn count_zeros(self) -> u32 {
     /// Returns the number of trailing zeros in the binary representation
     /// of `self`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -148,7 +148,7 @@ fn count_zeros(self) -> u32 {
     /// 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 @@ fn count_zeros(self) -> u32 {
     /// 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 @@ fn count_zeros(self) -> u32 {
 
     /// Reverses the byte order of the integer.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -198,7 +198,7 @@ fn count_zeros(self) -> u32 {
     ///
     /// 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 @@ fn from_be(x: Self) -> Self {
     ///
     /// 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 @@ fn from_le(x: Self) -> Self {
     ///
     /// 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 @@ fn to_be(self) -> Self { // or not to be?
     ///
     /// 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 @@ fn to_le(self) -> Self {
     /// Checked integer addition. Computes `self + other`, returning `None` if
     /// overflow occurred.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -303,7 +303,7 @@ fn to_le(self) -> Self {
     /// Checked integer subtraction. Computes `self - other`, returning `None`
     /// if underflow occurred.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -317,7 +317,7 @@ fn to_le(self) -> Self {
     /// Checked integer multiplication. Computes `self * other`, returning
     /// `None` if underflow or overflow occurred.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -331,7 +331,7 @@ fn to_le(self) -> Self {
     /// 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 @@ fn saturating_sub(self, other: Self) -> Self {
 
     /// Raises self to the power of `exp`, using exponentiation by squaring.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::num::Int;
@@ -1273,7 +1273,7 @@ impl FromPrimitive for $T {
 
 /// Cast from one machine scalar to another.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::num;

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 @@
 /// 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 @@ fn $method(self, other: &'a $u) -> <$t as $imp<$u>>::Output {
 
 /// 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 @@ fn add(self, other: $t) -> $t { self + other }
 
 /// 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 @@ fn sub(self, other: $t) -> $t { self - other }
 
 /// 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 @@ fn mul(self, other: $t) -> $t { self * other }
 
 /// 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 @@ fn div(self, other: $t) -> $t { self / other }
 
 /// 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 @@ fn rem(self, other: $t) -> $t {
 
 /// 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 @@ fn neg(self) -> $t { -(self as $t_signed) as $t }
 
 /// 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 @@ fn not(self) -> $t { !self }
 
 /// 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 @@ fn bitand(self, rhs: $t) -> $t { self & rhs }
 
 /// 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 @@ fn bitor(self, rhs: $t) -> $t { self | rhs }
 
 /// 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 @@ fn bitxor(self, other: $t) -> $t { self ^ other }
 
 /// 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 @@ macro_rules! shl_impl_all {
 
 /// 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 @@ macro_rules! shr_impl_all {
 /// 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 @@ fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
 /// 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 @@ fn deref(&self) -> &T { *self }
 /// 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.

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 @@ pub fn is_some(&self) -> bool {
 
     /// Returns `true` if the option is a `None` value
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x: Option<u32> = Some(2);
@@ -226,7 +226,7 @@ pub fn is_none(&self) -> bool {
 
     /// 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 @@ pub fn as_ref<'r>(&'r self) -> Option<&'r T> {
 
     /// Convert from `Option<T>` to `Option<&mut T>`
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let mut x = Some(2);
@@ -272,7 +272,7 @@ pub fn as_mut<'r>(&'r mut self) -> Option<&'r mut T> {
 
     /// Convert from `Option<T>` to `&mut [T]` (without copying)
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let mut x = Some("Diamonds");
@@ -311,7 +311,7 @@ pub fn as_mut_slice<'r>(&'r mut self) -> &'r mut [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 @@ pub fn expect(self, msg: &str) -> T {
     /// Instead, prefer to use pattern matching and handle the `None`
     /// case explicitly.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x = Some("air");
@@ -365,7 +365,7 @@ pub fn unwrap(self) -> T {
 
     /// Returns the contained value or a default.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// assert_eq!(Some("car").unwrap_or("bike"), "car");
@@ -382,7 +382,7 @@ pub fn unwrap_or(self, def: T) -> T {
 
     /// Returns the contained value or computes it from a closure.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let k = 10;
@@ -404,7 +404,7 @@ pub fn unwrap_or_else<F: FnOnce() -> T>(self, f: F) -> 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 @@ pub fn map<U, F: FnOnce(T) -> U>(self, f: F) -> Option<U> {
 
     /// Applies a function to the contained value or returns a default.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x = Some("foo");
@@ -444,7 +444,7 @@ pub fn map_or<U, F: FnOnce(T) -> U>(self, def: U, f: F) -> U {
 
     /// Applies a function to the contained value or computes a default.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let k = 21;
@@ -467,7 +467,7 @@ pub fn map_or_else<U, D: FnOnce() -> U, F: FnOnce(T) -> U>(self, def: D, f: F) -
     /// 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 @@ pub fn ok_or<E>(self, err: E) -> Result<T, E> {
     /// 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 @@ pub fn ok_or_else<E, F: FnOnce() -> E>(self, err: F) -> Result<T, E> {
 
     /// Returns an iterator over the possibly contained value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x = Some(4);
@@ -529,7 +529,7 @@ pub fn iter(&self) -> Iter<T> {
 
     /// Returns a mutable iterator over the possibly contained value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let mut x = Some(4);
@@ -551,7 +551,7 @@ pub fn iter_mut(&mut self) -> IterMut<T> {
 
     /// Returns a consuming iterator over the possibly contained value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x = Some("string");
@@ -574,7 +574,7 @@ pub fn into_iter(self) -> IntoIter<T> {
 
     /// Returns `None` if the option is `None`, otherwise returns `optb`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x = Some(2);
@@ -607,7 +607,7 @@ pub fn and<U>(self, optb: Option<U>) -> Option<U> {
     ///
     /// Some languages call this operation flatmap.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// fn sq(x: u32) -> Option<u32> { Some(x * x) }
@@ -629,7 +629,7 @@ pub fn and_then<U, F: FnOnce(T) -> Option<U>>(self, f: F) -> Option<U> {
 
     /// Returns the option if it contains a value, otherwise returns `optb`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x = Some(2);
@@ -660,7 +660,7 @@ pub fn or(self, optb: Option<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 @@ pub fn or_else<F: FnOnce() -> Option<T>>(self, f: F) -> 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

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 @@ pub fn is_ok(&self) -> bool {
 
     /// Returns true if the result is `Err`
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x: Result<int, &str> = Ok(-3);
@@ -309,7 +309,7 @@ pub fn is_err(&self) -> bool {
     /// 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 @@ pub fn ok(self) -> Option<T> {
     /// 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 @@ pub fn as_mut_slice(&mut self) -> &mut [T] {
     ///
     /// 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 @@ pub fn map<U, F: FnOnce(T) -> U>(self, op: F) -> Result<U,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 @@ pub fn map_err<F, O: FnOnce(E) -> F>(self, op: O) -> Result<T,F> {
 
     /// Returns an iterator over the possibly contained value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x: Result<u32, &str> = Ok(7);
@@ -522,7 +522,7 @@ pub fn iter(&self) -> Iter<T> {
 
     /// Returns a mutable iterator over the possibly contained value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let mut x: Result<u32, &str> = Ok(7);
@@ -543,7 +543,7 @@ pub fn iter_mut(&mut self) -> IterMut<T> {
 
     /// Returns a consuming iterator over the possibly contained value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let x: Result<u32, &str> = Ok(5);
@@ -566,7 +566,7 @@ pub fn into_iter(self) -> IntoIter<T> {
 
     /// 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 @@ pub fn and<U>(self, res: Result<U, E>) -> Result<U, 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 @@ pub fn and_then<U, F: FnOnce(T) -> Result<U, E>>(self, op: F) -> Result<U, 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 @@ pub fn or<F>(self, res: Result<T, F>) -> Result<T, F> {
     ///
     /// 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 @@ pub fn or_else<F, O: FnOnce(E) -> Result<T, F>>(self, op: O) -> Result<T, F> {
     /// Unwraps a result, yielding the content of an `Ok`.
     /// Else it returns `optb`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let optb = 2;
@@ -697,7 +697,7 @@ pub fn unwrap_or(self, optb: T) -> T {
     /// 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);

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;

src/libcore/str/mod.rs

@@ -1183,7 +1183,7 @@ fn partial_cmp(&self, other: &str) -> Option<Ordering> {
     /// 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";

src/libcore/str/pattern.rs

@@ -215,7 +215,7 @@ fn next_reject_back(&mut self) -> Option<(usize, usize)>{
 ///   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

src/liblog/macros.rs

@@ -16,7 +16,7 @@
 /// format!-based argument list. See documentation in `std::fmt` for details on
 /// how to use the syntax.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// #[macro_use] extern crate log;
@@ -64,7 +64,7 @@ macro_rules! log {
 
 /// A convenience macro for logging at the error log level.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// #[macro_use] extern crate log;
@@ -89,7 +89,7 @@ macro_rules! error {
 
 /// A convenience macro for logging at the warning log level.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// #[macro_use] extern crate log;
@@ -113,7 +113,7 @@ macro_rules! warn {
 
 /// A convenience macro for logging at the info log level.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// #[macro_use] extern crate log;
@@ -139,7 +139,7 @@ macro_rules! info {
 /// be omitted at compile time by passing `--cfg ndebug` to the compiler. If
 /// this option is not passed, then debug statements will be compiled.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// #[macro_use] extern crate log;
@@ -162,7 +162,7 @@ macro_rules! debug {
 
 /// A macro to test whether a log level is enabled for the current module.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// #[macro_use] extern crate log;

src/librand/distributions/exponential.rs

@@ -57,7 +57,7 @@ fn zero_case<R:Rng>(rng: &mut R, _u: f64) -> f64 {
 /// This distribution has density function: `f(x) = lambda *
 /// exp(-lambda * x)` for `x > 0`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::rand;

src/librand/distributions/gamma.rs

@@ -37,7 +37,7 @@
 /// == 1`, and using the boosting technique described in [1] for
 /// `shape < 1`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::rand;
@@ -184,7 +184,7 @@ fn ind_sample<R: Rng>(&self, rng: &mut R) -> f64 {
 /// `k`, this uses the equivalent characterisation `χ²(k) = Gamma(k/2,
 /// 2)`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::rand;
@@ -241,7 +241,7 @@ fn ind_sample<R: Rng>(&self, rng: &mut R) -> f64 {
 /// chi-squared distributions, that is, `F(m,n) = (χ²(m)/m) /
 /// (χ²(n)/n)`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::rand;
@@ -285,7 +285,7 @@ fn ind_sample<R: Rng>(&self, rng: &mut R) -> f64 {
 /// The Student t distribution, `t(nu)`, where `nu` is the degrees of
 /// freedom.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::rand;

src/librand/distributions/mod.rs

@@ -93,7 +93,7 @@ pub struct Weighted<T> {
 /// all `T`, as is `uint`, so one can store references or indices into
 /// another vector.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::rand;

src/librand/distributions/normal.rs

@@ -73,7 +73,7 @@ fn zero_case<R:Rng>(rng: &mut R, u: f64) -> f64 {
 /// This uses the ZIGNOR variant of the Ziggurat method, see
 /// `StandardNormal` for more details.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::rand;
@@ -121,7 +121,7 @@ fn ind_sample<R: Rng>(&self, rng: &mut R) -> f64 {
 /// If `X` is log-normal distributed, then `ln(X)` is `N(mean,
 /// std_dev**2)` distributed.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::rand;

src/librand/distributions/range.rs

@@ -33,7 +33,7 @@
 /// primitive integer types satisfy this property, and the float types
 /// normally satisfy it, but rounding may mean `high` can occur.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::rand::distributions::{IndependentSample, Range};

src/librand/lib.rs

@@ -146,7 +146,7 @@ fn next_f64(&mut self) -> f64 {
     /// (e.g. reading past the end of a file that is being used as the
     /// source of randomness).
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::rand::{thread_rng, Rng};
@@ -181,7 +181,7 @@ fn fill_bytes(&mut self, dest: &mut [u8]) {
 
     /// Return a random value of a `Rand` type.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::rand::{thread_rng, Rng};
@@ -199,7 +199,7 @@ fn gen<T: Rand>(&mut self) -> T {
     /// Return an iterator that will yield an infinite number of randomly
     /// generated items.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::rand::{thread_rng, Rng};
@@ -226,7 +226,7 @@ fn gen_iter<'a, T: Rand>(&'a mut self) -> Generator<'a, T, Self> {
     ///
     /// Panics if `low >= high`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::rand::{thread_rng, Rng};
@@ -244,7 +244,7 @@ fn gen_range<T: PartialOrd + SampleRange>(&mut self, low: T, high: T) -> T {
 
     /// Return a bool with a 1 in n chance of true
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::rand::{thread_rng, Rng};
@@ -258,7 +258,7 @@ fn gen_weighted_bool(&mut self, n: uint) -> bool {
 
     /// Return an iterator of random characters from the set A-Z,a-z,0-9.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::rand::{thread_rng, Rng};
@@ -274,7 +274,7 @@ fn gen_ascii_chars<'a>(&'a mut self) -> AsciiGenerator<'a, Self> {
     ///
     /// Return `None` if `values` is empty.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::rand::{thread_rng, Rng};
@@ -294,7 +294,7 @@ fn choose<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T> {
 
     /// Shuffle a mutable slice in place.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::rand::{thread_rng, Rng};
@@ -357,7 +357,7 @@ fn next(&mut self) -> Option<char> {
 pub trait SeedableRng<Seed>: Rng {
     /// Reseed an RNG with the given seed.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::rand::{Rng, SeedableRng, StdRng};
@@ -372,7 +372,7 @@ pub trait SeedableRng<Seed>: Rng {
 
     /// Create a new RNG with the given seed.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::rand::{Rng, SeedableRng, StdRng};
@@ -477,7 +477,7 @@ fn rand<R: Rng>(rng: &mut R) -> XorShiftRng {
 /// `Rand` implementation for `f32` and `f64` for the half-open
 /// `[0,1)`.
 ///
-/// # Example
+/// # Examples
 /// ```rust
 /// use std::rand::{random, Open01};
 ///
@@ -493,7 +493,7 @@ fn rand<R: Rng>(rng: &mut R) -> XorShiftRng {
 /// `Rand` implementation of `f32` and `f64` for the half-open
 /// `[0,1)`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::rand::{random, Closed01};

src/librand/reseeding.rs

@@ -100,7 +100,7 @@ fn from_seed((rsdr, seed): (Rsdr, S)) -> ReseedingRng<R, Rsdr> {
 
 /// Something that can be used to reseed an RNG via `ReseedingRng`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::rand::{Rng, SeedableRng, StdRng};

src/librbml/io.rs

@@ -36,7 +36,7 @@ fn combine(seek: SeekStyle, cur: uint, end: uint, offset: i64) -> IoResult<u64>
 
 /// Writes to an owned, growable byte vector that supports seeking.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// # #![allow(unused_must_use)]

src/librustc/util/common.rs

@@ -193,7 +193,7 @@ pub fn can_reach<T, S>(edges_map: &HashMap<T, Vec<T>, S>, source: T,
 /// ```
 /// but currently it is not possible.
 ///
-/// # Example
+/// # Examples
 /// ```
 /// struct Context {
 ///    cache: RefCell<HashMap<uint, uint>>

src/librustc_bitflags/lib.rs

@@ -29,7 +29,7 @@
 /// The flags should only be defined for integer types, otherwise unexpected
 /// type errors may occur at compile time.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```{.rust}
 /// #[macro_use] extern crate rustc_bitflags;

src/libserialize/hex.rs

@@ -29,7 +29,7 @@ pub trait ToHex {
 impl ToHex for [u8] {
     /// Turn a vector of `u8` bytes into a hexadecimal string.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// extern crate serialize;
@@ -96,7 +96,7 @@ impl FromHex for str {
     /// You can use the `String::from_utf8` function to turn a
     /// `Vec<u8>` into a string with characters corresponding to those values.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// This converts a string literal to hexadecimal and back.
     ///

src/libstd/collections/hash/map.rs

@@ -225,7 +225,7 @@ fn test_resize_policy() {
 /// 3. Emmanuel Goossaert. ["Robin Hood hashing: backward shift
 ///    deletion"](http://codecapsule.com/2013/11/17/robin-hood-hashing-backward-shift-deletion/)
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::collections::HashMap;
@@ -497,7 +497,7 @@ fn insert_hashed_ordered(&mut self, hash: SafeHash, k: K, v: V) {
 impl<K: Hash + Eq, V> HashMap<K, V, RandomState> {
     /// Create an empty HashMap.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -511,7 +511,7 @@ pub fn new() -> HashMap<K, V, RandomState> {
 
     /// Creates an empty hash map with the given initial capacity.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -531,7 +531,7 @@ impl<K, V, S> HashMap<K, V, S>
     ///
     /// The creates map has the default initial capacity.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -559,7 +559,7 @@ pub fn with_hash_state(hash_state: S) -> HashMap<K, V, S> {
     /// cause many collisions and very poor performance. Setting it
     /// manually using this function can expose a DoS attack vector.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -586,7 +586,7 @@ pub fn with_capacity_and_hash_state(capacity: usize, hash_state: S)
 
     /// Returns the number of elements the map can hold without reallocating.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -607,7 +607,7 @@ pub fn capacity(&self) -> usize {
     ///
     /// Panics if the new allocation size overflows `usize`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -714,7 +714,7 @@ fn resize(&mut self, new_capacity: usize) {
     /// down as much as possible while maintaining the internal rules
     /// and possibly leaving some space in accordance with the resize policy.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -806,7 +806,7 @@ fn insert_or_replace_with<'a, F>(&'a mut self,
     /// An iterator visiting all keys in arbitrary order.
     /// Iterator element type is `&'a K`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -831,7 +831,7 @@ fn first<A, B>((a, _): (A, B)) -> A { a }
     /// An iterator visiting all values in arbitrary order.
     /// Iterator element type is `&'a V`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -856,7 +856,7 @@ fn second<A, B>((_, b): (A, B)) -> B { b }
     /// An iterator visiting all key-value pairs in arbitrary order.
     /// Iterator element type is `(&'a K, &'a V)`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -879,7 +879,7 @@ pub fn iter(&self) -> Iter<K, V> {
     /// with mutable references to the values.
     /// Iterator element type is `(&'a K, &'a mut V)`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -907,7 +907,7 @@ pub fn iter_mut(&mut self) -> IterMut<K, V> {
     /// pair out of the map in arbitrary order. The map cannot be used after
     /// calling this.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -942,7 +942,7 @@ pub fn entry(&mut self, key: K) -> Entry<K, V> {
 
     /// Returns the number of elements in the map.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -957,7 +957,7 @@ pub fn len(&self) -> usize { self.table.size() }
 
     /// Returns true if the map contains no elements.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -974,7 +974,7 @@ pub fn is_empty(&self) -> bool { self.len() == 0 }
     /// Clears the map, returning all key-value pairs as an iterator. Keeps the
     /// allocated memory for reuse.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -1005,7 +1005,7 @@ fn last_two<A, B, C>((_, b, c): (A, B, C)) -> (B, C) { (b, c) }
     /// Clears the map, removing all key-value pairs. Keeps the allocated memory
     /// for reuse.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -1027,7 +1027,7 @@ pub fn clear(&mut self) {
     /// `Hash` and `Eq` on the borrowed form *must* match those for
     /// the key type.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -1050,7 +1050,7 @@ pub fn get<Q: ?Sized>(&self, k: &Q) -> Option<&V>
     /// `Hash` and `Eq` on the borrowed form *must* match those for
     /// the key type.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -1073,7 +1073,7 @@ pub fn contains_key<Q: ?Sized>(&self, k: &Q) -> bool
     /// `Hash` and `Eq` on the borrowed form *must* match those for
     /// the key type.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -1096,7 +1096,7 @@ pub fn get_mut<Q: ?Sized>(&mut self, k: &Q) -> Option<&mut V>
     /// Inserts a key-value pair from the map. If the key already had a value
     /// present in the map, that value is returned. Otherwise, `None` is returned.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;
@@ -1128,7 +1128,7 @@ pub fn insert(&mut self, k: K, v: V) -> Option<V> {
     /// `Hash` and `Eq` on the borrowed form *must* match those for
     /// the key type.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashMap;

src/libstd/collections/hash/set.rs

@@ -38,7 +38,7 @@
 /// HashMap where the value is (). As with the `HashMap` type, a `HashSet`
 /// requires that the elements implement the `Eq` and `Hash` traits.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::collections::HashSet;
@@ -100,7 +100,7 @@ pub struct HashSet<T, S = RandomState> {
 impl<T: Hash + Eq> HashSet<T, RandomState> {
     /// Create an empty HashSet.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -115,7 +115,7 @@ pub fn new() -> HashSet<T, RandomState> {
     /// Create an empty HashSet with space for at least `n` elements in
     /// the hash table.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -136,7 +136,7 @@ impl<T, S> HashSet<T, S>
     ///
     /// The hash set is also created with the default initial capacity.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -160,7 +160,7 @@ pub fn with_hash_state(hash_state: S) -> HashSet<T, S> {
     /// cause many collisions and very poor performance. Setting it
     /// manually using this function can expose a DoS attack vector.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -181,7 +181,7 @@ pub fn with_capacity_and_hash_state(capacity: usize, hash_state: S)
 
     /// Returns the number of elements the set can hold without reallocating.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -202,7 +202,7 @@ pub fn capacity(&self) -> usize {
     ///
     /// Panics if the new allocation size overflows `usize`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -218,7 +218,7 @@ pub fn reserve(&mut self, additional: usize) {
     /// down as much as possible while maintaining the internal rules
     /// and possibly leaving some space in accordance with the resize policy.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -238,7 +238,7 @@ pub fn shrink_to_fit(&mut self) {
     /// An iterator visiting all elements in arbitrary order.
     /// Iterator element type is &'a T.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -260,7 +260,7 @@ pub fn iter(&self) -> Iter<T> {
     /// of the set in arbitrary order. The set cannot be used after calling
     /// this.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -286,7 +286,7 @@ fn first<A, B>((a, _): (A, B)) -> A { a }
 
     /// Visit the values representing the difference.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -316,7 +316,7 @@ pub fn difference<'a>(&'a self, other: &'a HashSet<T, S>) -> Difference<'a, T, S
 
     /// Visit the values representing the symmetric difference.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -342,7 +342,7 @@ pub fn symmetric_difference<'a>(&'a self, other: &'a HashSet<T, S>)
 
     /// Visit the values representing the intersection.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -367,7 +367,7 @@ pub fn intersection<'a>(&'a self, other: &'a HashSet<T, S>) -> Intersection<'a,
 
     /// Visit the values representing the union.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -389,7 +389,7 @@ pub fn union<'a>(&'a self, other: &'a HashSet<T, S>) -> Union<'a, T, S> {
 
     /// Return the number of elements in the set
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -404,7 +404,7 @@ pub fn len(&self) -> usize { self.map.len() }
 
     /// Returns true if the set contains no elements
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -430,7 +430,7 @@ fn first<A, B>((a, _): (A, B)) -> A { a }
 
     /// Clears the set, removing all values.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -449,7 +449,7 @@ pub fn clear(&mut self) { self.map.clear() }
     /// `Hash` and `Eq` on the borrowed form *must* match those for
     /// the value type.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -468,7 +468,7 @@ pub fn contains<Q: ?Sized>(&self, value: &Q) -> bool
     /// Returns `true` if the set has no elements in common with `other`.
     /// This is equivalent to checking for an empty intersection.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -489,7 +489,7 @@ pub fn is_disjoint(&self, other: &HashSet<T, S>) -> bool {
 
     /// Returns `true` if the set is a subset of another.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -510,7 +510,7 @@ pub fn is_subset(&self, other: &HashSet<T, S>) -> bool {
 
     /// Returns `true` if the set is a superset of another.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -536,7 +536,7 @@ pub fn is_superset(&self, other: &HashSet<T, S>) -> bool {
     /// Adds a value to the set. Returns `true` if the value was not already
     /// present in the set.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;
@@ -557,7 +557,7 @@ pub fn insert(&mut self, value: T) -> bool { self.map.insert(value, ()).is_none(
     /// `Hash` and `Eq` on the borrowed form *must* match those for
     /// the value type.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::collections::HashSet;

src/libstd/env.rs

@@ -38,7 +38,7 @@
 /// * There are insufficient permissions to access the current directory.
 /// * The internal buffer is not large enough to hold the path.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::env;
@@ -55,7 +55,7 @@ pub fn current_dir() -> io::Result<PathBuf> {
 /// Changes the current working directory to the specified path, returning
 /// whether the change was completed successfully or not.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::env;
@@ -99,7 +99,7 @@ pub struct VarsOs { inner: os_imp::Env }
 /// environment is not valid unicode. If this is not desired, consider using the
 /// `env::vars_os` function.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::env;
@@ -122,7 +122,7 @@ pub fn vars() -> Vars {
 /// variables at the time of this invocation, modifications to environment
 /// variables afterwards will not be reflected in the returned iterator.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::env;
@@ -163,7 +163,7 @@ fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
 /// valid unicode. If the environment variable is not present, or it is not
 /// valid unicode, then `Err` will be returned.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::env;
@@ -185,7 +185,7 @@ pub fn var<K: ?Sized>(key: &K) -> Result<String, VarError> where K: AsOsStr {
 /// Fetches the environment variable `key` from the current process, returning
 /// None if the variable isn't set.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::env;
@@ -243,7 +243,7 @@ fn description(&self) -> &str {
 /// Sets the environment variable `k` to the value `v` for the currently running
 /// process.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::env;
@@ -279,7 +279,7 @@ pub struct SplitPaths<'a> { inner: os_imp::SplitPaths<'a> }
 ///
 /// Returns an iterator over the paths contained in `unparsed`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::env;
@@ -323,7 +323,7 @@ pub struct JoinPathsError {
 /// `Path`s contains an invalid character for constructing the `PATH`
 /// variable (a double quote on Windows or a colon on Unix).
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::env;
@@ -371,7 +371,7 @@ fn description(&self) -> &str { self.inner.description() }
 /// 'USERPROFILE' environment variable if it is set and not equal to the empty
 /// string.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::env;
@@ -478,7 +478,7 @@ pub struct ArgsOs { inner: os_imp::Args }
 /// process is not valid unicode. If this is not desired it is recommended to
 /// use the `args_os` function instead.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::env;
@@ -500,7 +500,7 @@ pub fn args() -> Args {
 /// set to arbitrary text, and it may not even exist, so this property should
 /// not be relied upon for security purposes.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::env;

src/libstd/ffi/c_str.rs

@@ -41,7 +41,7 @@
 /// a `CString` do *not* contain the trailing nul terminator unless otherwise
 /// specified.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```no_run
 /// # extern crate libc;
@@ -325,7 +325,7 @@ impl CStr {
     /// > currently implemented with an up-front calculation of the length of
     /// > the string. This is not guaranteed to always be the case.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # extern crate libc;

src/libstd/fs/mod.rs

@@ -36,7 +36,7 @@
 /// it was opened with. Files also implement `Seek` to alter the logical cursor
 /// that the file contains internally.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```no_run
 /// use std::io::prelude::*;
@@ -392,7 +392,7 @@ pub fn path(&self) -> PathBuf { self.0.path() }
 
 /// Remove a file from the underlying filesystem.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust,no_run
 /// use std::fs;
@@ -420,7 +420,7 @@ pub fn remove_file<P: AsPath + ?Sized>(path: &P) -> io::Result<()> {
 /// This function will traverse soft links to query information about the
 /// destination file.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust,no_run
 /// # fn foo() -> std::io::Result<()> {
@@ -444,7 +444,7 @@ pub fn metadata<P: AsPath + ?Sized>(path: &P) -> io::Result<Metadata> {
 
 /// Rename a file or directory to a new name.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust,no_run
 /// use std::fs;
@@ -472,7 +472,7 @@ pub fn rename<P: AsPath + ?Sized, Q: AsPath + ?Sized>(from: &P, to: &Q)
 /// Note that if `from` and `to` both point to the same file, then the file
 /// will likely get truncated by this operation.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::fs;
@@ -541,7 +541,7 @@ pub fn read_link<P: AsPath + ?Sized>(path: &P) -> io::Result<PathBuf> {
 
 /// Create a new, empty directory at the provided path
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::fs;
@@ -587,7 +587,7 @@ pub fn create_dir_all<P: AsPath + ?Sized>(path: &P) -> io::Result<()> {
 
 /// Remove an existing, empty directory
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::fs;
@@ -638,7 +638,7 @@ fn lstat(path: &Path) -> io::Result<fs_imp::FileAttr> { fs_imp::stat(path) }
 /// The iterator will yield instances of `io::Result<DirEntry>`. New errors may
 /// be encountered after an iterator is initially constructed.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::io;
@@ -776,7 +776,7 @@ pub fn set_file_times<P: AsPath + ?Sized>(path: &P, accessed: u64,
 
 /// Changes the permissions found on a file or a directory.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// # fn foo() -> std::io::Result<()> {

src/libstd/macros.rs

@@ -26,7 +26,7 @@
 /// The multi-argument form of this macro panics with a string and has the
 /// `format!` syntax for building a string.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```should_fail
 /// # #![allow(unreachable_code)]
@@ -74,7 +74,7 @@ macro_rules! print {
 /// The syntax of this macro is the same as that used for `format!`. For more
 /// information, see `std::fmt` and `std::old_io::stdio`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// println!("hello there!");
@@ -177,7 +177,7 @@ pub mod builtin {
     ///
     /// For more information, see the documentation in `std::fmt`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::fmt;
@@ -200,7 +200,7 @@ macro_rules! format_args { ($fmt:expr, $($args:tt)*) => ({
     /// will be emitted.  To not emit a compile error, use the `option_env!`
     /// macro instead.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let path: &'static str = env!("PATH");
@@ -219,7 +219,7 @@ macro_rules! env { ($name:expr) => ({ /* compiler built-in */ }) }
     /// A compile time error is never emitted when using this macro regardless
     /// of whether the environment variable is present or not.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let key: Option<&'static str> = option_env!("SECRET_KEY");
@@ -263,7 +263,7 @@ macro_rules! concat_idents {
     /// Integer and floating point literals are stringified in order to be
     /// concatenated.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let s = concat!("test", 10, 'b', true);
@@ -278,7 +278,7 @@ macro_rules! concat { ($($e:expr),*) => ({ /* compiler built-in */ }) }
     /// the invocation of the `line!()` macro itself, but rather the first macro
     /// invocation leading up to the invocation of the `line!()` macro.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let current_line = line!();
@@ -293,7 +293,7 @@ macro_rules! line { () => ({ /* compiler built-in */ }) }
     /// the invocation of the `column!()` macro itself, but rather the first macro
     /// invocation leading up to the invocation of the `column!()` macro.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let current_col = column!();
@@ -309,7 +309,7 @@ macro_rules! column { () => ({ /* compiler built-in */ }) }
     /// first macro invocation leading up to the invocation of the `file!()`
     /// macro.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let this_file = file!();
@@ -324,7 +324,7 @@ macro_rules! file { () => ({ /* compiler built-in */ }) }
     /// stringification of all the tokens passed to the macro. No restrictions
     /// are placed on the syntax of the macro invocation itself.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let one_plus_one = stringify!(1 + 1);
@@ -339,7 +339,7 @@ macro_rules! stringify { ($t:tt) => ({ /* compiler built-in */ }) }
     /// contents of the filename specified. The file is located relative to the
     /// current file (similarly to how modules are found),
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust,ignore
     /// let secret_key = include_str!("secret-key.ascii");
@@ -353,7 +353,7 @@ macro_rules! include_str { ($file:expr) => ({ /* compiler built-in */ }) }
     /// the contents of the filename specified. The file is located relative to
     /// the current file (similarly to how modules are found),
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust,ignore
     /// let secret_key = include_bytes!("secret-key.bin");
@@ -367,7 +367,7 @@ macro_rules! include_bytes { ($file:expr) => ({ /* compiler built-in */ }) }
     /// leading back up to the crate root. The first component of the path
     /// returned is the name of the crate currently being compiled.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// mod test {
@@ -390,7 +390,7 @@ macro_rules! module_path { () => ({ /* compiler built-in */ }) }
     /// The syntax given to this macro is the same syntax as the `cfg`
     /// attribute.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let my_directory = if cfg!(windows) {

src/libstd/net/mod.rs

@@ -82,7 +82,7 @@ fn next(&mut self) -> Option<io::Result<SocketAddr>> { self.0.next() }
 /// This method may perform a DNS query to resolve `host` and may also inspect
 /// system configuration to resolve the specified hostname.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```no_run
 /// use std::net;

src/libstd/net/tcp.rs

@@ -21,7 +21,7 @@
 ///
 /// The socket will be closed when the value is dropped.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```no_run
 /// use std::io::prelude::*;

src/libstd/net/udp.rs

@@ -21,7 +21,7 @@
 /// IPv6 addresses, and there is no corresponding notion of a server because UDP
 /// is a datagram protocol.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```no_run
 /// use std::net::UdpSocket;

src/libstd/old_io/buffered.rs

@@ -31,7 +31,7 @@
 /// `BufferedReader` performs large, infrequent reads on the underlying
 /// `Reader` and maintains an in-memory buffer of the results.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::old_io::{BufferedReader, File};
@@ -134,7 +134,7 @@ fn read(&mut self, buf: &mut [u8]) -> IoResult<uint> {
 ///
 /// This writer will be flushed when it is dropped.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::old_io::{BufferedWriter, File};
@@ -320,7 +320,7 @@ fn read(&mut self, buf: &mut [u8]) -> IoResult<uint> {
 ///
 /// The output half will be flushed when this stream is dropped.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// # #![allow(unused_must_use)]

src/libstd/old_io/comm_adapters.rs

@@ -20,7 +20,7 @@
 
 /// Allows reading from a rx.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::sync::mpsc::channel;
@@ -111,7 +111,7 @@ fn read(&mut self, buf: &mut [u8]) -> IoResult<uint> {
 
 /// Allows writing to a tx.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// # #![allow(unused_must_use)]

src/libstd/old_io/fs.rs

@@ -27,7 +27,7 @@
 //! the metadata of a file. This includes getting the `stat` information,
 //! reading off particular bits of it, etc.
 //!
-//! # Example
+//! # Examples
 //!
 //! ```rust
 //! # #![allow(unused_must_use)]
@@ -102,7 +102,7 @@ impl File {
     /// Open a file at `path` in the mode specified by the `mode` and `access`
     /// arguments
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust,should_fail
     /// use std::old_io::{File, Open, ReadWrite};
@@ -173,7 +173,7 @@ pub fn open_mode(path: &Path,
     ///
     /// For more information, see the `File::open_mode` function.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::old_io::File;
@@ -192,7 +192,7 @@ pub fn open(path: &Path) -> IoResult<File> {
     ///
     /// For more information, see the `File::open_mode` function.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// # #![allow(unused_must_use)]
@@ -283,7 +283,7 @@ pub fn stat(&self) -> IoResult<FileStat> {
 
 /// Unlink a file from the underlying filesystem.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// # #![allow(unused_must_use)]
@@ -314,7 +314,7 @@ pub fn unlink(path: &Path) -> IoResult<()> {
 /// directory, etc. This function will traverse symlinks to query
 /// information about the destination file.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::old_io::fs;
@@ -356,7 +356,7 @@ pub fn lstat(path: &Path) -> IoResult<FileStat> {
 
 /// Rename a file or directory to a new name.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// # #![allow(unused_must_use)]
@@ -384,7 +384,7 @@ pub fn rename(from: &Path, to: &Path) -> IoResult<()> {
 /// Note that if `from` and `to` both point to the same file, then the file
 /// will likely get truncated by this operation.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// # #![allow(unused_must_use)]
@@ -434,7 +434,7 @@ fn update_err<T>(result: IoResult<T>, from: &Path, to: &Path) -> IoResult<T> {
 /// Changes the permission mode bits found on a file or a directory. This
 /// function takes a mask from the `io` module
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// # #![allow(unused_must_use)]
@@ -505,7 +505,7 @@ pub fn readlink(path: &Path) -> IoResult<Path> {
 
 /// Create a new, empty directory at the provided path
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// # #![allow(unused_must_use)]
@@ -529,7 +529,7 @@ pub fn mkdir(path: &Path, mode: FilePermission) -> IoResult<()> {
 
 /// Remove an existing, empty directory
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// # #![allow(unused_must_use)]
@@ -553,7 +553,7 @@ pub fn rmdir(path: &Path) -> IoResult<()> {
 
 /// Retrieve a vector containing all entries within a provided directory
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::old_io::fs::PathExtensions;

src/libstd/old_io/mem.rs

@@ -51,7 +51,7 @@ fn write_all(&mut self, buf: &[u8]) -> IoResult<()> {
 
 /// Writes to an owned, growable byte vector
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// # #![allow(unused_must_use)]
@@ -111,7 +111,7 @@ fn write_all(&mut self, buf: &[u8]) -> IoResult<()> {
 
 /// Reads from an owned byte vector
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// # #![allow(unused_must_use)]
@@ -241,7 +241,7 @@ fn consume(&mut self, amt: uint) {
 /// If a write will not fit in the buffer, it returns an error and does not
 /// write any data.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// # #![allow(unused_must_use)]
@@ -313,7 +313,7 @@ fn seek(&mut self, pos: i64, style: SeekStyle) -> IoResult<()> {
 
 /// Reads from a fixed-size byte slice
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// # #![allow(unused_must_use)]

src/libstd/old_io/mod.rs

@@ -1276,7 +1276,7 @@ fn flush(&mut self) -> IoResult<()> { (**self).flush() }
 /// A `RefWriter` is a struct implementing `Writer` which contains a reference
 /// to another writer. This is often useful when composing streams.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::old_io::util::TeeReader;
@@ -1401,7 +1401,7 @@ pub trait Buffer: Reader {
     /// encoded Unicode codepoints. If a newline is encountered, then the
     /// newline is contained in the returned string.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::old_io::BufReader;
@@ -1625,7 +1625,7 @@ fn next(&mut self) -> Option<IoResult<T>> {
 /// Creates a standard error for a commonly used flavor of error. The `detail`
 /// field of the returned error will always be `None`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::old_io as io;

src/libstd/old_io/net/pipe.rs

@@ -50,7 +50,7 @@ impl UnixStream {
     ///
     /// The returned stream will be closed when the object falls out of scope.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// # #![allow(unused_must_use)]
@@ -175,7 +175,7 @@ impl UnixListener {
     ///
     /// This listener will be closed when it falls out of scope.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # fn foo() {

src/libstd/old_io/net/tcp.rs

@@ -38,7 +38,7 @@
 ///
 /// The socket will be closed when the value is dropped.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```no_run
 /// use std::old_io::TcpStream;
@@ -130,7 +130,7 @@ pub fn set_keepalive(&mut self, delay_in_seconds: Option<uint>) -> IoResult<()>
     /// This method will close the reading portion of this connection, causing
     /// all pending and future reads to immediately return with an error.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// # #![allow(unused_must_use)]
@@ -373,7 +373,7 @@ impl TcpAcceptor {
     /// regardless of whether the timeout has expired or not (the accept will
     /// not block in this case).
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// use std::old_io::TcpListener;
@@ -417,7 +417,7 @@ impl TcpAcceptor {
     /// This is useful for waking up a thread in an accept loop to indicate that
     /// it should exit.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::old_io::{TcpListener, Listener, Acceptor, EndOfFile};

src/libstd/old_io/net/udp.rs

@@ -28,7 +28,7 @@
 /// IPv6 addresses, and there is no corresponding notion of a server because UDP
 /// is a datagram protocol.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust,no_run
 /// # #![allow(unused_must_use)]

src/libstd/old_io/pipe.rs

@@ -43,7 +43,7 @@ impl PipeStream {
     /// This operation consumes ownership of the file descriptor and it will be
     /// closed once the object is deallocated.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```{rust,no_run}
     /// # #![allow(unused_must_use)]

src/libstd/old_io/process.rs

@@ -57,7 +57,7 @@
 /// process is created via the `Command` struct, which configures the spawning
 /// process and can itself be constructed using a builder-style interface.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```should_fail
 /// use std::old_io::Command;
@@ -361,7 +361,7 @@ pub fn spawn(&self) -> IoResult<Process> {
     /// Executes the command as a child process, waiting for it to finish and
     /// collecting all of its output.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::old_io::Command;
@@ -382,7 +382,7 @@ pub fn output(&self) -> IoResult<ProcessOutput> {
     /// Executes a command as a child process, waiting for it to finish and
     /// collecting its exit status.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::old_io::Command;
@@ -656,7 +656,7 @@ pub fn wait(&mut self) -> IoResult<ProcessExit> {
     /// A value of `None` will clear any previous timeout, and a value of `Some`
     /// will override any previously set timeout.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// use std::old_io::{Command, IoResult};

src/libstd/old_io/stdio.rs

@@ -15,7 +15,7 @@
 //! inspected for information about terminal dimensions or for related information
 //! about the stream or terminal to which it is attached.
 //!
-//! # Example
+//! # Examples
 //!
 //! ```rust
 //! # #![allow(unused_must_use)]

src/libstd/old_io/timer.rs

@@ -113,7 +113,7 @@ pub fn sleep(&mut self, duration: Duration) {
     /// invalidated at the end of that statement, and all `recv` calls will
     /// fail.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::old_io::Timer;
@@ -165,7 +165,7 @@ pub fn oneshot(&mut self, duration: Duration) -> Receiver<()> {
     /// invalidated at the end of that statement, and all `recv` calls will
     /// fail.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use std::old_io::Timer;

src/libstd/old_path/mod.rs

@@ -46,7 +46,7 @@
 //! suitable for passing to any API that actually operates on the path; it is only intended for
 //! display.
 //!
-//! ## Example
+//! ## Examples
 //!
 //! ```rust
 //! use std::old_io::fs::PathExtensions;
@@ -140,7 +140,7 @@ pub trait GenericPath: Clone + GenericPathUnsafe {
     /// Creates a new Path from a byte vector or string.
     /// The resulting Path will always be normalized.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -164,7 +164,7 @@ fn new<T: BytesContainer>(path: T) -> Self {
     /// Creates a new Path from a byte vector or string, if possible.
     /// The resulting Path will always be normalized.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -186,7 +186,7 @@ fn new_opt<T: BytesContainer>(path: T) -> Option<Self> {
     /// Returns the path as a string, if possible.
     /// If the path is not representable in utf-8, this returns None.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -203,7 +203,7 @@ fn as_str<'a>(&'a self) -> Option<&'a str> {
 
     /// Returns the path as a byte vector
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -217,7 +217,7 @@ fn as_str<'a>(&'a self) -> Option<&'a str> {
 
     /// Converts the Path into an owned byte vector
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -232,7 +232,7 @@ fn as_str<'a>(&'a self) -> Option<&'a str> {
 
     /// Returns an object that implements `Display` for printing paths
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -250,7 +250,7 @@ fn display<'a>(&'a self) -> Display<'a, Self> {
     ///
     /// If there is no filename, nothing will be printed.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -267,7 +267,7 @@ fn filename_display<'a>(&'a self) -> Display<'a, Self> {
     /// Returns the directory component of `self`, as a byte vector (with no trailing separator).
     /// If `self` has no directory component, returns ['.'].
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -282,7 +282,7 @@ fn filename_display<'a>(&'a self) -> Display<'a, Self> {
     /// Returns the directory component of `self`, as a string, if possible.
     /// See `dirname` for details.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -301,7 +301,7 @@ fn dirname_str<'a>(&'a self) -> Option<&'a str> {
     /// If `self` represents the root of the file hierarchy, returns None.
     /// If `self` is "." or "..", returns None.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -316,7 +316,7 @@ fn dirname_str<'a>(&'a self) -> Option<&'a str> {
     /// Returns the file component of `self`, as a string, if possible.
     /// See `filename` for details.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -335,7 +335,7 @@ fn filename_str<'a>(&'a self) -> Option<&'a str> {
     /// The stem is the portion of the filename just before the last '.'.
     /// If there is no '.', the entire filename is returned.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -362,7 +362,7 @@ fn filestem<'a>(&'a self) -> Option<&'a [u8]> {
     /// Returns the stem of the filename of `self`, as a string, if possible.
     /// See `filestem` for details.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -382,7 +382,7 @@ fn filestem_str<'a>(&'a self) -> Option<&'a str> {
     /// If there is no extension, None is returned.
     /// If the filename ends in '.', the empty vector is returned.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -409,7 +409,7 @@ fn extension<'a>(&'a self) -> Option<&'a [u8]> {
     /// Returns the extension of the filename of `self`, as a string, if possible.
     /// See `extension` for details.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -427,7 +427,7 @@ fn extension_str<'a>(&'a self) -> Option<&'a str> {
     /// Replaces the filename portion of the path with the given byte vector or string.
     /// If the replacement name is [], this is equivalent to popping the path.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -453,7 +453,7 @@ fn set_filename<T: BytesContainer>(&mut self, filename: T) {
     /// If the argument is [] or "", this removes the extension.
     /// If `self` has no filename, this is a no-op.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -503,7 +503,7 @@ fn set_extension<T: BytesContainer>(&mut self, extension: T) {
     /// byte vector or string.
     /// See `set_filename` for details.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -528,7 +528,7 @@ fn with_filename<T: BytesContainer>(&self, filename: T) -> Self {
     /// byte vector or string.
     /// See `set_extension` for details.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -552,7 +552,7 @@ fn with_extension<T: BytesContainer>(&self, extension: T) -> Self {
     /// Returns the directory component of `self`, as a Path.
     /// If `self` represents the root of the filesystem hierarchy, returns `self`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -571,7 +571,7 @@ fn dir_path(&self) -> Self {
     ///
     /// If `self` is not absolute, or vol/cwd-relative in the case of Windows, this returns None.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -586,7 +586,7 @@ fn dir_path(&self) -> Self {
     /// Pushes a path (as a byte vector or string) onto `self`.
     /// If the argument represents an absolute path, it replaces `self`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -610,7 +610,7 @@ fn push<T: BytesContainer>(&mut self, path: T) {
     /// Pushes multiple paths (as byte vectors or strings) onto `self`.
     /// See `push` for details.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -639,7 +639,7 @@ fn push_many<T: BytesContainer>(&mut self, paths: &[T]) {
     /// Returns `true` if the receiver was modified, or `false` if it already
     /// represented the root of the file hierarchy.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -656,7 +656,7 @@ fn push_many<T: BytesContainer>(&mut self, paths: &[T]) {
     /// (as a byte vector or string).
     /// If the given path is absolute, the new Path will represent just that.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -681,7 +681,7 @@ fn join<T: BytesContainer>(&self, path: T) -> Self {
     /// (as byte vectors or strings).
     /// See `join` for details.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -703,7 +703,7 @@ fn join_many<T: BytesContainer>(&self, paths: &[T]) -> Self {
     /// An absolute path is defined as one that, when joined to another path, will
     /// yield back the same absolute path.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -720,7 +720,7 @@ fn join_many<T: BytesContainer>(&self, paths: &[T]) -> Self {
     /// But for Windows paths, it also means the path is not volume-relative or
     /// relative to the current working directory.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -738,7 +738,7 @@ fn is_relative(&self) -> bool {
     /// If both paths are relative, they are compared as though they are relative
     /// to the same parent path.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -757,7 +757,7 @@ fn is_relative(&self) -> bool {
     /// If `self` is absolute and `base` is relative, or on Windows if both
     /// paths refer to separate drives, an absolute path is returned.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();
@@ -773,7 +773,7 @@ fn is_relative(&self) -> bool {
 
     /// Returns whether the relative path `child` is a suffix of `self`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # foo();

src/libstd/old_path/windows.rs

@@ -603,7 +603,7 @@ impl Path {
     ///
     /// Panics if the vector contains a `NUL`, or if it contains invalid UTF-8.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// println!("{}", Path::new(r"C:\some\path").display());
@@ -617,7 +617,7 @@ pub fn new<T: BytesContainer>(path: T) -> Path {
     ///
     /// Returns `None` if the vector contains a `NUL`, or if it contains invalid UTF-8.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let path = Path::new_opt(r"C:\some\path");

src/libstd/os.rs

@@ -121,7 +121,7 @@ pub fn num_cpus() -> uint {
 /// * There are insufficient permissions to access the current directory.
 /// * The internal buffer is not large enough to hold the path.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::os;
@@ -141,7 +141,7 @@ pub fn getcwd() -> IoResult<Path> {
 /// Invalid UTF-8 bytes are replaced with \uFFFD. See `String::from_utf8_lossy()`
 /// for details.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::os;
@@ -177,7 +177,7 @@ pub fn env_as_bytes() -> Vec<(Vec<u8>, Vec<u8>)> {
 ///
 /// Panics if `n` has any interior NULs.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::os;
@@ -219,7 +219,7 @@ fn byteify(s: OsString) -> Vec<u8> {
 /// Sets the environment variable `n` to the value `v` for the currently running
 /// process.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::os;
@@ -260,7 +260,7 @@ pub fn unsetenv(n: &str) {
 /// Parses input according to platform conventions for the `PATH`
 /// environment variable.
 ///
-/// # Example
+/// # Examples
 /// ```rust
 /// use std::os;
 ///
@@ -291,7 +291,7 @@ pub fn split_paths<T: BytesContainer>(unparsed: T) -> Vec<Path> {
 /// `Path`s contains an invalid character for constructing the `PATH`
 /// variable (a double quote on Windows or a colon on Unix).
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::os;
@@ -372,7 +372,7 @@ pub fn self_exe_name() -> Option<Path> {
 ///
 /// Like self_exe_name() but without the binary's name.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::os;
@@ -401,7 +401,7 @@ pub fn self_exe_path() -> Option<Path> {
 /// 'USERPROFILE' environment variable if it is set and not equal to the empty
 /// string.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::os;
@@ -491,7 +491,7 @@ fn lookup() -> Path {
 /// directory. If the given path is already an absolute path, return it
 /// as is.
 ///
-/// # Example
+/// # Examples
 /// ```rust
 /// use std::os;
 /// use std::old_path::Path;
@@ -522,7 +522,7 @@ pub fn make_absolute(p: &Path) -> IoResult<Path> {
 /// Changes the current working directory to the specified path, returning
 /// whether the change was completed successfully or not.
 ///
-/// # Example
+/// # Examples
 /// ```rust
 /// use std::os;
 /// use std::old_path::Path;
@@ -543,7 +543,7 @@ pub fn errno() -> i32 {
 
 /// Return the string corresponding to an `errno()` value of `errnum`.
 ///
-/// # Example
+/// # Examples
 /// ```rust
 /// use std::os;
 ///
@@ -739,7 +739,7 @@ fn CommandLineToArgvW(lpCmdLine: LPCWSTR,
 ///
 /// The arguments are interpreted as utf-8, with invalid bytes replaced with \uFFFD.
 /// See `String::from_utf8_lossy` for details.
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::os;

src/libstd/path.rs

@@ -809,7 +809,7 @@ fn cmp(&self, other: &Components<'a>) -> cmp::Ordering {
 /// More details about the overall approach can be found in
 /// the module documentation.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::path::PathBuf;
@@ -1041,7 +1041,7 @@ fn as_os_str(&self) -> &OsStr {
 /// This is an *unsized* type, meaning that it must always be used with behind a
 /// pointer like `&` or `Box`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::path::Path;

src/libstd/process.rs

@@ -35,7 +35,7 @@
 /// process is created via the `Command` struct, which configures the spawning
 /// process and can itself be constructed using a builder-style interface.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```should_fail
 /// # #![feature(process)]
@@ -288,7 +288,7 @@ pub fn output(&mut self) -> io::Result<Output> {
     ///
     /// By default, stdin, stdout and stderr are inherited by the parent.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # #![feature(process)]

src/libstd/rand/mod.rs

@@ -424,7 +424,7 @@ pub fn random<T: Rand>() -> T {
 
 /// Randomly sample up to `amount` elements from an iterator.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::rand::{thread_rng, sample};

src/libstd/rand/reader.rs

@@ -22,7 +22,7 @@
 ///
 /// It will panic if it there is insufficient data to fulfill a request.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::rand::{reader, Rng};

src/libstd/sync/condvar.rs

@@ -34,7 +34,7 @@
 /// in a runtime panic. If this is not desired, then the unsafe primitives in
 /// `sys` do not have this restriction but may result in undefined behavior.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::sync::{Arc, Mutex, Condvar};
@@ -66,7 +66,7 @@ pub struct Condvar { inner: Box<StaticCondvar> }
 /// This structure is identical to `Condvar` except that it is suitable for use
 /// in static initializers for other structures.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::sync::{StaticCondvar, CONDVAR_INIT};

src/libstd/sync/mpsc/mod.rs

@@ -464,7 +464,7 @@ fn inner_unsafe<'a>(&'a self) -> &'a UnsafeCell<Flavor<T>> {
 /// All data sent on the sender will become available on the receiver, and no
 /// send will block the calling task (this channel has an "infinite buffer").
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::sync::mpsc::channel;
@@ -506,7 +506,7 @@ pub fn channel<T: Send>() -> (Sender<T>, Receiver<T>) {
 /// As with asynchronous channels, all senders will panic in `send` if the
 /// `Receiver` has been destroyed.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::sync::mpsc::sync_channel;
@@ -555,7 +555,7 @@ fn new(inner: Flavor<T>) -> Sender<T> {
     ///
     /// This method will never block the current thread.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use std::sync::mpsc::channel;

src/libstd/sync/mpsc/select.rs

@@ -24,7 +24,7 @@
 //! received values of receivers in a much more natural syntax then usage of the
 //! `Select` structure directly.
 //!
-//! # Example
+//! # Examples
 //!
 //! ```rust
 //! use std::sync::mpsc::channel;

src/libstd/sync/mutex.rs

@@ -133,7 +133,7 @@ unsafe impl<T: Send> Sync for Mutex<T> { }
 /// to a `Mutex`, a `destroy` method. This method is unsafe to call, and
 /// documentation can be found directly on the method.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::sync::{StaticMutex, MUTEX_INIT};

src/libstd/sync/once.rs

@@ -24,7 +24,7 @@
 /// functionality. This type can only be constructed with the `ONCE_INIT`
 /// value.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::sync::{Once, ONCE_INIT};

src/libstd/sync/rwlock.rs

@@ -74,7 +74,7 @@ unsafe impl<T: Send + Sync> Sync for RwLock<T> {}
 /// automatic global access as well as lazy initialization. The internal
 /// resources of this RwLock, however, must be manually deallocated.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::sync::{StaticRwLock, RW_LOCK_INIT};

src/libstd/sync/semaphore.rs

@@ -22,7 +22,7 @@
 /// until the counter is positive, and each release will increment the counter
 /// and unblock any threads if necessary.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::sync::Semaphore;

src/libstd/sync/task_pool.rs

@@ -58,7 +58,7 @@ fn drop(&mut self) {
 /// Spawns `n` worker threads and replenishes the pool if any worker threads
 /// panic.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use std::sync::TaskPool;

src/libstd/sys/common/thread_local.rs

@@ -28,7 +28,7 @@
 //! more useful in practice than this OS-based version which likely requires
 //! unsafe code to interoperate with.
 //!
-//! # Example
+//! # Examples
 //!
 //! Using a dynamically allocated TLS key. Note that this key can be shared
 //! among many threads via an `Arc`.
@@ -73,7 +73,7 @@
 /// time. The key is also deallocated when the Rust runtime exits or `destroy`
 /// is called, whichever comes first.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```ignore
 /// use tls::os::{StaticKey, INIT};
@@ -110,7 +110,7 @@ pub struct StaticKeyInner {
 /// Implementations will likely, however, contain unsafe code as this type only
 /// operates on `*mut u8`, an unsafe pointer.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust,ignore
 /// use tls::os::Key;

src/libstd/sys/windows/c.rs

@@ -300,7 +300,7 @@ fn store_func(ptr: &AtomicUsize, module: &str, symbol: &str,
 
     /// Macro for creating a compatibility fallback for a Windows function
     ///
-    /// # Example
+    /// # Examples
     /// ```
     /// compat_fn!(adll32::SomeFunctionW(_arg: LPCWSTR) {
     ///     // Fallback implementation

src/libstd/thread_local/mod.rs

@@ -68,7 +68,7 @@ pub mod __impl {
 /// within a thread, and values support destructors which will be run when a
 /// thread exits.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::cell::RefCell;

src/libstd/thread_local/scoped.rs

@@ -21,7 +21,7 @@
 //! period of time and it is not required to relinquish ownership of the
 //! contents.
 //!
-//! # Example
+//! # Examples
 //!
 //! ```
 //! scoped_thread_local!(static FOO: u32);
@@ -139,7 +139,7 @@ impl<T> Key<T> {
     /// Upon return, this function will restore the previous value, if any
     /// was available.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// scoped_thread_local!(static FOO: u32);
@@ -191,7 +191,7 @@ fn drop(&mut self) {
     ///
     /// This function will panic if `set` has not previously been called.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```no_run
     /// scoped_thread_local!(static FOO: u32);

src/libsyntax/parse/parser.rs

@@ -5372,7 +5372,7 @@ fn parse_foreign_mod_items(&mut self,
 
     /// Parse extern crate links
     ///
-    /// # Example
+    /// # Examples
     ///
     /// extern crate url;
     /// extern crate foo = "bar"; //deprecated

src/libunicode/u_str.rs

@@ -479,7 +479,7 @@ fn size_hint(&self) -> (usize, Option<usize>) {
 /// Create an iterator over the UTF-16 encoded codepoints in `v`,
 /// returning invalid surrogates as `LoneSurrogate`s.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust
 /// use unicode::str::Utf16Item::{ScalarValue, LoneSurrogate};