Add missing urls and few local rewrites

1 files changed, 92 insertions, 54 deletions

diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs
index 5a12f5db19d..f6b74a91c19 100644
--- a/src/libcore/iter/iterator.rs
+++ b/src/libcore/iter/iterator.rs
@@ -35,11 +35,14 @@ pub trait Iterator {
 
     /// Advances the iterator and returns the next value.
     ///
-    /// Returns `None` when iteration is finished. Individual iterator
+    /// Returns [`None`] when iteration is finished. Individual iterator
     /// implementations may choose to resume iteration, and so calling `next()`
-    /// again may or may not eventually start returning `Some(Item)` again at some
+    /// again may or may not eventually start returning [`Some(Item)`] again at some
     /// point.
     ///
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
+    /// [`Some(Item)`]: ../../std/option/enum.Option.html#variant.Some
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -69,9 +72,9 @@ pub trait Iterator {
     /// Specifically, `size_hint()` returns a tuple where the first element
     /// is the lower bound, and the second element is the upper bound.
     ///
-    /// The second half of the tuple that is returned is an `Option<usize>`. A
-    /// `None` here means that either there is no known upper bound, or the
-    /// upper bound is larger than `usize`.
+    /// The second half of the tuple that is returned is an [`Option`]`<`[`usize`]`>`.
+    /// A [`None`] here means that either there is no known upper bound, or the
+    /// upper bound is larger than [`usize`].
     ///
     /// # Implementation notes
     ///
@@ -91,6 +94,10 @@ pub trait Iterator {
     /// The default implementation returns `(0, None)` which is correct for any
     /// iterator.
     ///
+    /// [`usize`]: ../../std/primitive.usize.html
+    /// [`Option`]: ../../std/option/enum.Option.html
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -134,23 +141,26 @@ pub trait Iterator {
     /// Consumes the iterator, counting the number of iterations and returning it.
     ///
     /// This method will evaluate the iterator until its [`next()`] returns
-    /// `None`. Once `None` is encountered, `count()` returns the number of
+    /// [`None`]. Once [`None`] is encountered, `count()` returns the number of
     /// times it called [`next()`].
     ///
     /// [`next()`]: #tymethod.next
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
     ///
     /// # Overflow Behavior
     ///
     /// The method does no guarding against overflows, so counting elements of
-    /// an iterator with more than `usize::MAX` elements either produces the
+    /// an iterator with more than [`usize::MAX`] elements either produces the
     /// wrong result or panics. If debug assertions are enabled, a panic is
     /// guaranteed.
     ///
     /// # Panics
     ///
-    /// This function might panic if the iterator has more than `usize::MAX`
+    /// This function might panic if the iterator has more than [`usize::MAX`]
     /// elements.
     ///
+    /// [`usize::MAX`]: ../../std/isize/constant.MAX.html
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -172,10 +182,12 @@ pub trait Iterator {
 
     /// Consumes the iterator, returning the last element.
     ///
-    /// This method will evaluate the iterator until it returns `None`. While
-    /// doing so, it keeps track of the current element. After `None` is
+    /// This method will evaluate the iterator until it returns [`None`]. While
+    /// doing so, it keeps track of the current element. After [`None`] is
     /// returned, `last()` will then return the last element it saw.
     ///
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -202,9 +214,11 @@ pub trait Iterator {
     /// Like most indexing operations, the count starts from zero, so `nth(0)`
     /// returns the first value, `nth(1)` the second, and so on.
     ///
-    /// `nth()` will return `None` if `n` is greater than or equal to the length of the
+    /// `nth()` will return [`None`] if `n` is greater than or equal to the length of the
     /// iterator.
     ///
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -306,8 +320,8 @@ pub trait Iterator {
     ///
     /// In other words, it zips two iterators together, into a single one.
     ///
-    /// When either iterator returns `None`, all further calls to `next()`
-    /// will return `None`.
+    /// When either iterator returns [`None`], all further calls to [`next()`]
+    /// will return [`None`].
     ///
     /// # Examples
     ///
@@ -346,7 +360,7 @@ pub trait Iterator {
     /// ```
     ///
     /// `zip()` is often used to zip an infinite iterator to a finite one.
-    /// This works because the finite iterator will eventually return `None`,
+    /// This works because the finite iterator will eventually return [`None`],
     /// ending the zipper. Zipping with `(0..)` can look a lot like [`enumerate()`]:
     ///
     /// ```
@@ -365,6 +379,8 @@ pub trait Iterator {
     /// ```
     ///
     /// [`enumerate()`]: trait.Iterator.html#method.enumerate
+    /// [`next()`]: ../../std/iter/trait.Iterator.html#tymethod.next
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     fn zip<U>(self, other: U) -> Zip<Self, U::IntoIter> where
@@ -501,11 +517,9 @@ pub trait Iterator {
     ///
     /// The closure must return an [`Option<T>`]. `filter_map()` creates an
     /// iterator which calls this closure on each element. If the closure
-    /// returns `Some(element)`, then that element is returned. If the
-    /// closure returns `None`, it will try again, and call the closure on the
-    /// next element, seeing if it will return `Some`.
-    ///
-    /// [`Option<T>`]: ../../std/option/enum.Option.html
+    /// returns [`Some(element)`][`Some`], then that element is returned. If the
+    /// closure returns [`None`], it will try again, and call the closure on the
+    /// next element, seeing if it will return [`Some`].
     ///
     /// Why `filter_map()` and not just [`filter()`].[`map()`]? The key is in this
     /// part:
@@ -513,11 +527,11 @@ pub trait Iterator {
     /// [`filter()`]: #method.filter
     /// [`map()`]: #method.map
     ///
-    /// > If the closure returns `Some(element)`, then that element is returned.
+    /// > If the closure returns [`Some(element)`][`Some`], then that element is returned.
     ///
     /// In other words, it removes the [`Option<T>`] layer automatically. If your
     /// mapping is already returning an [`Option<T>`] and you want to skip over
-    /// `None`s, then `filter_map()` is much, much nicer to use.
+    /// [`None`]s, then `filter_map()` is much, much nicer to use.
     ///
     /// # Examples
     ///
@@ -547,7 +561,11 @@ pub trait Iterator {
     /// assert_eq!(iter.next(), None);
     /// ```
     ///
-    /// There's an extra layer of `Some` in there.
+    /// There's an extra layer of [`Some`] in there.
+    ///
+    /// [`Option<T>`]: ../../std/option/enum.Option.html
+    /// [`Some`]: ../../std/option/enum.Option.html#variant.Some
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F> where
@@ -567,21 +585,20 @@ pub trait Iterator {
     /// different sized integer, the [`zip()`] function provides similar
     /// functionality.
     ///
-    /// [`usize`]: ../../std/primitive.usize.html
-    /// [`zip()`]: #method.zip
-    ///
     /// # Overflow Behavior
     ///
     /// The method does no guarding against overflows, so enumerating more than
     /// [`usize::MAX`] elements either produces the wrong result or panics. If
     /// debug assertions are enabled, a panic is guaranteed.
     ///
-    /// [`usize::MAX`]: ../../std/usize/constant.MAX.html
-    ///
     /// # Panics
     ///
     /// The returned iterator might panic if the to-be-returned index would
-    /// overflow a `usize`.
+    /// overflow a [`usize`].
+    ///
+    /// [`usize::MAX`]: ../../std/usize/constant.MAX.html
+    /// [`usize`]: ../../std/primitive.usize.html
+    /// [`zip()`]: #method.zip
     ///
     /// # Examples
     ///
@@ -607,12 +624,13 @@ pub trait Iterator {
     /// Adds a [`peek()`] method to an iterator. See its documentation for
     /// more information.
     ///
-    /// Note that the underlying iterator is still advanced when `peek` is
+    /// Note that the underlying iterator is still advanced when [`peek()`] is
     /// called for the first time: In order to retrieve the next element,
-    /// `next` is called on the underlying iterator, hence any side effects of
-    /// the `next` method will occur.
+    /// [`next()`] is called on the underlying iterator, hence any side effects of
+    /// the [`next()`] method will occur.
     ///
     /// [`peek()`]: struct.Peekable.html#method.peek
+    /// [`next()`]: ../../std/iter/trait.Iterator.html#tymethod.next
     ///
     /// # Examples
     ///
@@ -894,12 +912,12 @@ pub trait Iterator {
     /// an extra layer of indirection. `flat_map()` will remove this extra layer
     /// on its own.
     ///
-    /// [`map()`]: #method.map
-    ///
     /// Another way of thinking about `flat_map()`: [`map()`]'s closure returns
     /// one item for each element, and `flat_map()`'s closure returns an
     /// iterator for each element.
     ///
+    /// [`map()`]: #method.map
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -921,11 +939,14 @@ pub trait Iterator {
         FlatMap{iter: self, f: f, frontiter: None, backiter: None }
     }
 
-    /// Creates an iterator which ends after the first `None`.
+    /// Creates an iterator which ends after the first [`None`].
     ///
-    /// After an iterator returns `None`, future calls may or may not yield
-    /// `Some(T)` again. `fuse()` adapts an iterator, ensuring that after a
-    /// `None` is given, it will always return `None` forever.
+    /// After an iterator returns [`None`], future calls may or may not yield
+    /// [`Some(T)`] again. `fuse()` adapts an iterator, ensuring that after a
+    /// [`None`] is given, it will always return [`None`] forever.
+    ///
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
+    /// [`Some(T)`]: ../../std/option/enum.Option.html#variant.Some
     ///
     /// # Examples
     ///
@@ -1082,19 +1103,15 @@ pub trait Iterator {
     /// library, used in a variety of contexts.
     ///
     /// The most basic pattern in which `collect()` is used is to turn one
-    /// collection into another. You take a collection, call `iter()` on it,
+    /// collection into another. You take a collection, call [`iter()`] on it,
     /// do a bunch of transformations, and then `collect()` at the end.
     ///
     /// One of the keys to `collect()`'s power is that many things you might
     /// not think of as 'collections' actually are. For example, a [`String`]
     /// is a collection of [`char`]s. And a collection of [`Result<T, E>`] can
-    /// be thought of as single `Result<Collection<T>, E>`. See the examples
+    /// be thought of as single [`Result`]`<Collection<T>, E>`. See the examples
     /// below for more.
     ///
-    /// [`String`]: ../../std/string/struct.String.html
-    /// [`Result<T, E>`]: ../../std/result/enum.Result.html
-    /// [`char`]: ../../std/primitive.char.html
-    ///
     /// Because `collect()` is so general, it can cause problems with type
     /// inference. As such, `collect()` is one of the few times you'll see
     /// the syntax affectionately known as the 'turbofish': `::<>`. This
@@ -1172,7 +1189,7 @@ pub trait Iterator {
     /// assert_eq!("hello", hello);
     /// ```
     ///
-    /// If you have a list of [`Result<T, E>`]s, you can use `collect()` to
+    /// If you have a list of [`Result<T, E>`][`Result`]s, you can use `collect()` to
     /// see if any of them failed:
     ///
     /// ```
@@ -1190,6 +1207,11 @@ pub trait Iterator {
     /// // gives us the list of answers
     /// assert_eq!(Ok(vec![1, 3]), result);
     /// ```
+    ///
+    /// [`iter()`]: ../../std/iter/trait.Iterator.html#tymethod.next
+    /// [`String`]: ../../std/string/struct.String.html
+    /// [`char`]: ../../std/primitive.char.html
+    /// [`Result`]: ../../std/result/enum.Result.html
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     fn collect<B: FromIterator<Self::Item>>(self) -> B where Self: Sized {
@@ -1281,6 +1303,8 @@ pub trait Iterator {
     /// use a `for` loop with a list of things to build up a result. Those
     /// can be turned into `fold()`s:
     ///
+    /// [`for`]: ../../book/loops.html#for
+    ///
     /// ```
     /// let numbers = [1, 2, 3, 4, 5];
     ///
@@ -1414,8 +1438,8 @@ pub trait Iterator {
     ///
     /// `find()` takes a closure that returns `true` or `false`. It applies
     /// this closure to each element of the iterator, and if any of them return
-    /// `true`, then `find()` returns `Some(element)`. If they all return
-    /// `false`, it returns `None`.
+    /// `true`, then `find()` returns [`Some(element)`]. If they all return
+    /// `false`, it returns [`None`].
     ///
     /// `find()` is short-circuiting; in other words, it will stop processing
     /// as soon as the closure returns `true`.
@@ -1425,6 +1449,9 @@ pub trait Iterator {
     /// argument is a double reference. You can see this effect in the
     /// examples below, with `&&x`.
     ///
+    /// [`Some(element)`]: ../../std/option/enum.Option.html#variant.Some
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -1465,8 +1492,8 @@ pub trait Iterator {
     ///
     /// `position()` takes a closure that returns `true` or `false`. It applies
     /// this closure to each element of the iterator, and if one of them
-    /// returns `true`, then `position()` returns `Some(index)`. If all of
-    /// them return `false`, it returns `None`.
+    /// returns `true`, then `position()` returns [`Some(index)`]. If all of
+    /// them return `false`, it returns [`None`].
     ///
     /// `position()` is short-circuiting; in other words, it will stop
     /// processing as soon as it finds a `true`.
@@ -1474,7 +1501,7 @@ pub trait Iterator {
     /// # Overflow Behavior
     ///
     /// The method does no guarding against overflows, so if there are more
-    /// than `usize::MAX` non-matching elements, it either produces the wrong
+    /// than [`usize::MAX`] non-matching elements, it either produces the wrong
     /// result or panics. If debug assertions are enabled, a panic is
     /// guaranteed.
     ///
@@ -1483,6 +1510,10 @@ pub trait Iterator {
     /// This function might panic if the iterator has more than `usize::MAX`
     /// non-matching elements.
     ///
+    /// [`Some(index)`]: ../../std/option/enum.Option.html#variant.Some
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
+    /// [`usize::MAX`]: ../../std/usize/constant.MAX.html
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -1528,11 +1559,14 @@ pub trait Iterator {
     /// `rposition()` takes a closure that returns `true` or `false`. It applies
     /// this closure to each element of the iterator, starting from the end,
     /// and if one of them returns `true`, then `rposition()` returns
-    /// `Some(index)`. If all of them return `false`, it returns `None`.
+    /// [`Some(index)`]. If all of them return `false`, it returns [`None`].
     ///
     /// `rposition()` is short-circuiting; in other words, it will stop
     /// processing as soon as it finds a `true`.
     ///
+    /// [`Some(index)`]: ../../std/option/enum.Option.html#variant.Some
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -1798,11 +1832,13 @@ pub trait Iterator {
         (ts, us)
     }
 
-    /// Creates an iterator which `clone()`s all of its elements.
+    /// Creates an iterator which [`clone()`]s all of its elements.
     ///
     /// This is useful when you have an iterator over `&T`, but you need an
     /// iterator over `T`.
     ///
+    /// [`clone()`]: ../../std/clone/trait.Clone.html#tymethod.clone
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -1827,10 +1863,12 @@ pub trait Iterator {
 
     /// Repeats an iterator endlessly.
     ///
-    /// Instead of stopping at `None`, the iterator will instead start again,
+    /// Instead of stopping at [`None`], the iterator will instead start again,
     /// from the beginning. After iterating again, it will start at the
     /// beginning again. And again. And again. Forever.
     ///
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -1862,7 +1900,7 @@ pub trait Iterator {
     ///
     /// # Panics
     ///
-    /// When calling `sum` and a primitive integer type is being returned, this
+    /// When calling `sum()` and a primitive integer type is being returned, this
     /// method will panic if the computation overflows and debug assertions are
     /// enabled.
     ///
@@ -1890,7 +1928,7 @@ pub trait Iterator {
     ///
     /// # Panics
     ///
-    /// When calling `product` and a primitive integer type is being returned,
+    /// When calling `product()` and a primitive integer type is being returned,
     /// method will panic if the computation overflows and debug assertions are
     /// enabled.
     ///