Improve documentation and slice impl

Author: kleimkuhler

src/libcore/iter/iterator.rs

@@ -2640,7 +2640,9 @@ pub trait Iterator {
     ///
     /// Instead of using `PartialOrd::partial_cmp`, this function uses the given `compare`
     /// function to determine the ordering of two elements. Apart from that, it's equivalent to
-    /// `is_sorted`; see its documentation for more information.
+    /// [`is_sorted`]; see its documentation for more information.
+    ///
+    /// [`is_sorted`]: trait.Iterator.html#method.is_sorted
     #[unstable(feature = "is_sorted", reason = "new API", issue = "53485")]
     fn is_sorted_by<F>(mut self, mut compare: F) -> bool
     where
@@ -2666,9 +2668,11 @@ pub trait Iterator {
     /// function.
     ///
     /// Instead of comparing the iterator's elements directly, this function compares the keys of
-    /// the elements, as determined by `f`. Apart from that, it's equivalent to `is_sorted`; see
+    /// the elements, as determined by `f`. Apart from that, it's equivalent to [`is_sorted`]; see
     /// its documentation for more information.
     ///
+    /// [`is_sorted`]: trait.Iterator.html#method.is_sorted
+    ///
     /// # Examples
     ///
     /// ```

src/libcore/slice/mod.rs

@@ -2285,22 +2285,23 @@ impl<T> [T] {
     ///
     /// Instead of using `PartialOrd::partial_cmp`, this function uses the given `compare`
     /// function to determine the ordering of two elements. Apart from that, it's equivalent to
-    /// `is_sorted`; see its documentation for more information.
+    /// [`is_sorted`]; see its documentation for more information.
+    ///
+    /// [`is_sorted`]: #method.is_sorted
     #[unstable(feature = "is_sorted", reason = "new API", issue = "53485")]
     pub fn is_sorted_by<F>(&self, mut compare: F) -> bool
     where
         F: FnMut(&T, &T) -> Option<Ordering>
     {
-        let mut last = match self.first() {
-            Some(e) => e,
-            None => return true,
-        };
+        let len = self.len();
+        if len <= 1 {
+            return true;
+        }
 
-        for curr in &self[1..] {
-            if compare(&last, &curr).map(|o| o == Ordering::Greater).unwrap_or(true) {
+        for i in 1..len {
+            if compare(&self[i - 1], &self[i]).map(|o| o == Ordering::Greater).unwrap_or(true) {
                 return false;
             }
-            last = &curr;
         }
 
         true
@@ -2309,9 +2310,11 @@ impl<T> [T] {
     /// Checks if the elements of this slice are sorted using the given key extraction function.
     ///
     /// Instead of comparing the slice's elements directly, this function compares the keys of the
-    /// elements, as determined by `f`. Apart from that, it's equivalent to `is_sorted`; see its
+    /// elements, as determined by `f`. Apart from that, it's equivalent to [`is_sorted`]; see its
     /// documentation for more information.
     ///
+    /// [`is_sorted`]: #method.is_sorted
+    ///
     /// # Examples
     ///
     /// ```