Make it clearer what String::leak is useful for

Author: jonhoo

library/alloc/src/string.rs

@@ -1940,8 +1940,9 @@ impl String {
 
     /// Converts this `String` into a <code>[Box]<[str]></code>.
     ///
-    /// This will drop any excess capacity.
+    /// Before doing the conversion, this method discards excess capacity like [`shrink_to_fit`].
     ///
+    /// [`shrink_to_fit`]: String::shrink_to_fit
     /// [str]: prim@str "str"
     ///
     /// # Examples
@@ -1969,8 +1970,11 @@ impl String {
     ///
     /// It does not reallocate or shrink the `String`,
     /// so the leaked allocation may include unused capacity that is not part
-    /// of the returned slice. If you don't want that, call [`into_boxed_str`],
-    /// and then [`Box::leak`].
+    /// of the returned slice. The advantage of this is that it avoids the potential
+    /// reallocation that [`shrink_to_fit`] may perform.
+    /// 
+    /// If you want to discard excess capacity, call [`into_boxed_str`],
+    /// and then [`Box::leak`] instead.
     ///
     /// [`into_boxed_str`]: Self::into_boxed_str
     ///