Rollup merge of #38995 - petrochenkov:minmax, r=GuillaumeGomez

Fix docs for min/max algorithms

I thought at first "what did they think about when stabilizing this!?", but it turned out it's just wrong docs. Phew.

r? @steveklabnik

Test:
```
use std::cmp::Ordering;

struct S(u8, u8);

impl PartialEq for S {
    fn eq(&self, other: &Self) -> bool {
        self.0 == other.0
    }
}
impl PartialOrd for S {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.0.cmp(&other.0))
    }
}
impl Ord for S {
    fn cmp(&self, other: &Self) -> Ordering {
        self.0.cmp(&other.0)
    }
}

fn main() {
    let arr = [S(0, 1), S(0, 2)];
    println!("min {:?}", arr.iter().min());
    println!("min_by {:?}", arr.iter().min_by(|x, y| x.0.cmp(&y.0)));
    println!("min_by_key {:?}", arr.iter().min_by_key(|x| x.0));
    println!("max {:?}", arr.iter().max());
    println!("max_by {:?}", arr.iter().max_by(|x, y| x.0.cmp(&y.0)));
    println!("max_by_key {:?}", arr.iter().max_by_key(|x| x.0));
}
```
Output:
```
rustc 1.15.0-beta.3 (a035041ba 2017-01-07)
min Some(S(0, 1))
min_by Some(S(0, 1))
min_by_key Some(S(0, 1))
max Some(S(0, 2))
max_by Some(S(0, 2))
max_by_key Some(S(0, 2))
```

1 files changed, 10 insertions, 10 deletions

diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs
index ec590d2bd06..91c09c55305 100644
--- a/src/libcore/iter/iterator.rs
+++ b/src/libcore/iter/iterator.rs
@@ -1612,7 +1612,7 @@ pub trait Iterator {
 
     /// Returns the maximum element of an iterator.
     ///
-    /// If the two elements are equally maximum, the latest element is
+    /// If several elements are equally maximum, the last element is
     /// returned.
     ///
     /// # Examples
@@ -1638,7 +1638,7 @@ pub trait Iterator {
 
     /// Returns the minimum element of an iterator.
     ///
-    /// If the two elements are equally minimum, the first element is
+    /// If several elements are equally minimum, the first element is
     /// returned.
     ///
     /// # Examples
@@ -1665,8 +1665,8 @@ pub trait Iterator {
     /// Returns the element that gives the maximum value from the
     /// specified function.
     ///
-    /// Returns the rightmost element if the comparison determines two elements
-    /// to be equally maximum.
+    /// If several elements are equally maximum, the last element is
+    /// returned.
     ///
     /// # Examples
     ///
@@ -1690,8 +1690,8 @@ pub trait Iterator {
     /// Returns the element that gives the maximum value with respect to the
     /// specified comparison function.
     ///
-    /// Returns the rightmost element if the comparison determines two elements
-    /// to be equally maximum.
+    /// If several elements are equally maximum, the last element is
+    /// returned.
     ///
     /// # Examples
     ///
@@ -1715,8 +1715,8 @@ pub trait Iterator {
     /// Returns the element that gives the minimum value from the
     /// specified function.
     ///
-    /// Returns the latest element if the comparison determines two elements
-    /// to be equally minimum.
+    /// If several elements are equally minimum, the first element is
+    /// returned.
     ///
     /// # Examples
     ///
@@ -1739,8 +1739,8 @@ pub trait Iterator {
     /// Returns the element that gives the minimum value with respect to the
     /// specified comparison function.
     ///
-    /// Returns the latest element if the comparison determines two elements
-    /// to be equally minimum.
+    /// If several elements are equally minimum, the first element is
+    /// returned.
     ///
     /// # Examples
     ///