Rollup merge of rust-lang#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

Author: Manishearth

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 @@ use heap::deallocate;
 
 /// 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 @@ impl<T : ?Sized> Box<T> {
 /// 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 @@ impl<T> ToOwned for T where T: 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 @@ impl<'a, K: Ord, V> OccupiedEntry<'a, K, 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 @@ use string;
 ///
 ///   * 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 @@ pub trait SliceExt {
     ///
     /// 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 @@ pub trait SliceExt {
     ///
     /// 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 @@ pub trait SliceExt {
     /// `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 @@ pub trait SliceExt {
 
     /// Return the number of elements in the slice
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let a = [1, 2, 3];
@@ -427,7 +427,7 @@ pub trait SliceExt {
 
     /// Returns true if the slice has a length of 0
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// let a = [1, 2, 3];
@@ -529,7 +529,7 @@ pub trait SliceExt {
     ///
     /// Panics if `a` or `b` are out of bounds.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let mut v = ["a", "b", "c", "d"];
@@ -549,7 +549,7 @@ pub trait SliceExt {
     ///
     /// Panics if `mid > len`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let mut v = [1, 2, 3, 4, 5, 6];
@@ -578,7 +578,7 @@ pub trait SliceExt {
 
     /// Reverse the order of elements in a slice, in place.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// let mut v = [1, 2, 3];
@@ -638,7 +638,7 @@ pub trait SliceExt {
     /// 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 @@ pub trait SliceExt {
     /// `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 @@ pub trait SliceExt {
     /// 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 @@ pub trait SliceExt {
     /// 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 @@ pub trait StrExt: Index<RangeFull, Output = str> {
     ///
     /// 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 @@ 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;

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;

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.
 ///

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