Slice total example: Move closer to total defn

Author: Havvy

src/liballoc/slice.rs

@@ -218,6 +218,15 @@ impl<T> [T] {
     /// * total and antisymmetric: exactly one of a < b, a == b or a > b is true; and
     /// * transitive, a < b and b < c implies a < c. The same must hold for both == and >.
     ///
+    /// For example, while `f64` doesn't implement `Ord` because `NaN != NaN`, we can use
+    /// `partial_cmp` as our sort function when we know the slice doesn't contain a `NaN`.
+    ///
+    /// ```
+    /// let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
+    /// floats.sort_by(|a, b| a.partial_cmp(b).unwrap());
+    /// assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);
+    /// ```
+    ///
     /// When applicable, unstable sorting is preferred because it is generally faster than stable
     /// sorting and it doesn't allocate auxiliary memory.
     /// See [`sort_unstable_by`](#method.sort_unstable_by).
@@ -242,12 +251,6 @@ impl<T> [T] {
     /// // reverse sorting
     /// v.sort_by(|a, b| b.cmp(a));
     /// assert!(v == [5, 4, 3, 2, 1]);
-    ///
-    /// // While f64 doesn't implement Ord because NaN != NaN, we can use
-    /// // partial_cmp here because we know none of the elements are NaN.
-    /// let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
-    /// floats.sort_by(|a, b| a.partial_cmp(b).unwrap());
-    /// assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]

src/libcore/slice/mod.rs

@@ -1346,6 +1346,15 @@ impl<T> [T] {
     /// * total and antisymmetric: exactly one of a < b, a == b or a > b is true; and
     /// * transitive, a < b and b < c implies a < c. The same must hold for both == and >.
     ///
+    /// For example, while `f64` doesn't implement `Ord` because `NaN != NaN`, we can use
+    /// `partial_cmp` as our sort function when we know the slice doesn't contain a `NaN`.
+    ///
+    /// ```
+    /// let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
+    /// floats.sort_by(|a, b| a.partial_cmp(b).unwrap());
+    /// assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);
+    /// ```
+    ///
     /// # Current implementation
     ///
     /// The current algorithm is based on [pattern-defeating quicksort][pdqsort] by Orson Peters,
@@ -1367,12 +1376,6 @@ impl<T> [T] {
     /// // reverse sorting
     /// v.sort_unstable_by(|a, b| b.cmp(a));
     /// assert!(v == [5, 4, 3, 2, 1]);
-    ///
-    /// // While f64 doesn't implement Ord because NaN != NaN, we can use
-    /// // partial_cmp here because we know none of the elements are NaN.
-    /// let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
-    /// floats.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
-    /// assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);
     /// ```
     ///
     /// [pdqsort]: https://github.com/orlp/pdqsort