Revert "Remove mentions of unstable sort_by_cached key from stable do…

…cumentation"

This reverts commit 9c7b69e.

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).

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
  ///
  /// ```