Revert "Remove mentions of unstable sort_by_cached key from stable documentation"

This reverts commit 9c7b69e17909ceb090a1c4b8882a4e0924a2a755.

2 files changed, 8 insertions, 0 deletions

diff --git a/src/liballoc/slice.rs b/src/liballoc/slice.rs
index 1f68efd019b..f4b2d463778 100644
--- a/src/liballoc/slice.rs
+++ b/src/liballoc/slice.rs
@@ -257,6 +257,10 @@ impl<T> [T] {
     /// This sort is stable (i.e., does not reorder equal elements) and `O(m n log(m n))`
     /// worst-case, where the key function is `O(m)`.
     ///
+    /// For expensive key functions (e.g. functions that are not simple property accesses or
+    /// basic operations), [`sort_by_cached_key`](#method.sort_by_cached_key) is likely to be
+    /// significantly faster, as it does not recompute element keys.
+    ///
     /// 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_key`](#method.sort_unstable_by_key).
diff --git a/src/libcore/slice/mod.rs b/src/libcore/slice/mod.rs
index acca9748372..a628fd0cfa4 100644
--- a/src/libcore/slice/mod.rs
+++ b/src/libcore/slice/mod.rs
@@ -1563,6 +1563,10 @@ impl<T> [T] {
     /// randomization to avoid degenerate cases, but with a fixed seed to always provide
     /// deterministic behavior.
     ///
+    /// Due to its key calling strategy, [`sort_unstable_by_key`](#method.sort_unstable_by_key)
+    /// is likely to be slower than [`sort_by_cached_key`](#method.sort_by_cached_key) in
+    /// cases where the key function is expensive.
+    ///
     /// # Examples
     ///
     /// ```