reword edge-conditions documentation on all slice 'sort' functions; resolves#130122

Author: BatmanAoD

library/alloc/src/slice.rs

@@ -180,10 +180,9 @@ impl<T> [T] {
 /// This sort is stable (i.e., does not reorder equal elements) and *O*(*n* \* log(*n*))
 /// worst-case.
 ///
-/// If the implementation of [`Ord`] for `T` does not implement a [total order] the resulting
-/// order of elements in the slice is unspecified. All original elements will remain in the
-/// slice and any possible modifications via interior mutability are observed in the input. Same
-/// is true if the implementation of [`Ord`] for `T` panics.
+/// If the implementation of [`Ord`] for `T` does not implement a [total order], the function
+/// may panic; even if the function exits normally, the resulting order of elements in the slice
+/// is unspecified. See also the note on panicking below.
 ///
 /// When applicable, unstable sorting is preferred because it is generally faster than stable
 /// sorting and it doesn't allocate auxiliary memory. See
@@ -212,7 +211,15 @@ impl<T> [T] {
 ///
 /// # Panics
 ///
-/// May panic if the implementation of [`Ord`] for `T` does not implement a [total order].
+/// May panic if the implementation of [`Ord`] for `T` does not implement a [total order], or if
+/// the [`Ord`] implementation itself panics.
+///
+/// All safe functions on slices preserve the invariant that even if the function panics, all
+/// original elements will remain in the slice and any possible modifications via interior
+/// mutability are observed in the input. This ensures that recovery code (for instance inside
+/// of a `Drop` or following a `catch_unwind`) will still have access to all the original
+/// elements. For instance, if the slice belongs to a `Vec`, the `Vec::drop` method will be able
+/// to dispose of all contained elements.
 ///
 /// # Examples
 ///
@@ -241,10 +248,9 @@ impl<T> [T] {
 /// This sort is stable (i.e., does not reorder equal elements) and *O*(*n* \* log(*n*))
 /// worst-case.
 ///
-/// If the comparison function `compare` does not implement a [total order] the resulting order
-/// of elements in the slice is unspecified. All original elements will remain in the slice and
-/// any possible modifications via interior mutability are observed in the input. Same is true
-/// if `compare` panics.
+/// If the comparison function `compare` does not implement a [total order], the function may
+/// panic; even if the function exits normally, the resulting order of elements in the slice is
+/// unspecified. See also the note on panicking below.
 ///
 /// For example `|a, b| (a - b).cmp(a)` is a comparison function that is neither transitive nor
 /// reflexive nor total, `a < b < c < a` with `a = 1, b = 2, c = 3`. For more information and
@@ -263,7 +269,14 @@ impl<T> [T] {
 ///
 /// # Panics
 ///
-/// May panic if `compare` does not implement a [total order].
+/// May panic if `compare` does not implement a [total order], or if `compare` itself panics.
+///
+/// All safe functions on slices preserve the invariant that even if the function panics, all
+/// original elements will remain in the slice and any possible modifications via interior
+/// mutability are observed in the input. This ensures that recovery code (for instance inside
+/// of a `Drop` or following a `catch_unwind`) will still have access to all the original
+/// elements. For instance, if the slice belongs to a `Vec`, the `Vec::drop` method will be able
+/// to dispose of all contained elements.
 ///
 /// # Examples
 ///
@@ -295,10 +308,9 @@ impl<T> [T] {
 /// This sort is stable (i.e., does not reorder equal elements) and *O*(*m* \* *n* \* log(*n*))
 /// worst-case, where the key function is *O*(*m*).
 ///
-/// If the implementation of [`Ord`] for `K` does not implement a [total order] the resulting
-/// order of elements in the slice is unspecified. All original elements will remain in the
-/// slice and any possible modifications via interior mutability are observed in the input. Same
-/// is true if the implementation of [`Ord`] for `K` panics.
+/// If the implementation of [`Ord`] for `K` does not implement a [total order], the function
+/// may panic; even if the function exits normally, the resulting order of elements in the slice
+/// is unspecified. See also the note on panicking below.
 ///
 /// # Current implementation
 ///
@@ -313,7 +325,15 @@ impl<T> [T] {
 ///
 /// # Panics
 ///
-/// May panic if the implementation of [`Ord`] for `K` does not implement a [total order].
+/// May panic if the implementation of [`Ord`] for `K` does not implement a [total order], or if
+/// the [`Ord`] implementation or the key-function `f` panics.
+///
+/// All safe functions on slices preserve the invariant that even if the function panics, all
+/// original elements will remain in the slice and any possible modifications via interior
+/// mutability are observed in the input. This ensures that recovery code (for instance inside
+/// of a `Drop` or following a `catch_unwind`) will still have access to all the original
+/// elements. For instance, if the slice belongs to a `Vec`, the `Vec::drop` method will be able
+/// to dispose of all contained elements.
 ///
 /// # Examples
 ///
@@ -347,10 +367,9 @@ impl<T> [T] {
 /// storage to remember the results of key evaluation. The order of calls to the key function is
 /// unspecified and may change in future versions of the standard library.
 ///
-/// If the implementation of [`Ord`] for `K` does not implement a [total order] the resulting
-/// order of elements in the slice is unspecified. All original elements will remain in the
-/// slice and any possible modifications via interior mutability are observed in the input. Same
-/// is true if the implementation of [`Ord`] for `K` panics.
+/// If the implementation of [`Ord`] for `K` does not implement a [total order], the function
+/// may panic; even if the function exits normally, the resulting order of elements in the slice
+/// is unspecified. See also the note on panicking below.
 ///
 /// For simple key functions (e.g., functions that are property accesses or basic operations),
 /// [`sort_by_key`](slice::sort_by_key) is likely to be faster.
@@ -369,7 +388,15 @@ impl<T> [T] {
 ///
 /// # Panics
 ///
-/// May panic if the implementation of [`Ord`] for `K` does not implement a [total order].
+/// May panic if the implementation of [`Ord`] for `K` does not implement a [total order], or if
+/// the [`Ord`] implementation panics.
+///
+/// All safe functions on slices preserve the invariant that even if the function panics, all
+/// original elements will remain in the slice and any possible modifications via interior
+/// mutability are observed in the input. This ensures that recovery code (for instance inside
+/// of a `Drop` or following a `catch_unwind`) will still have access to all the original
+/// elements. For instance, if the slice belongs to a `Vec`, the `Vec::drop` method will be able
+/// to dispose of all contained elements.
 ///
 /// # Examples
 ///