more doc improvements

Author: invpt

library/alloc/src/vec/mod.rs

@@ -358,7 +358,7 @@ mod spec_extend;
 ///
 /// `vec![x; n]`, `vec![a, b, c, d]`, and
 /// [`Vec::with_capacity(n)`][`Vec::with_capacity`], will all produce a `Vec`
-/// with exactly the requested capacity. If <code>[len] == [capacity]</code>,
+/// with at least the requested capacity. If <code>[len] == [capacity]</code>,
 /// (as is the case for the [`vec!`] macro), then a `Vec<T>` can be converted to
 /// and from a [`Box<[T]>`][owned slice] without reallocating or moving the elements.
 ///
@@ -1025,8 +1025,9 @@ impl<T, A: Allocator> Vec<T, A> {
     ///
     /// The behavior of this method depends on the allocator being used. If the allocator supports
     /// in-place shrinking, some or all of the excess capacity may be returned to the allocator.
-    /// If not, this method may cause the vector's data to be copied to a new allocation with
-    /// exactly the correct size. See [`Allocator::shrink`] for more details.
+    /// If not, this method may cause the vector's data to be copied to a new allocation, although
+    /// no guarantees are given that this new allocation is actually smaller. See
+    /// [`Allocator::shrink`] for more details.
     ///
     /// # Examples
     ///
@@ -1076,7 +1077,7 @@ impl<T, A: Allocator> Vec<T, A> {
 
     /// Converts the vector into [`Box<[T]>`][owned slice].
     ///
-    /// Before doing the conversion, this method calls [`shrink_to_fit`] to remove excess capacity.
+    /// Before doing the conversion, this method discards excess capacity like [`shrink_to_fit`].
     ///
     /// [owned slice]: Box
     /// [`shrink_to_fit`]: Vec::shrink_to_fit
@@ -3290,10 +3291,12 @@ impl<T, A: Allocator> From<Box<[T], A>> for Vec<T, A> {
 #[cfg(not(test))]
 #[stable(feature = "box_from_vec", since = "1.20.0")]
 impl<T, A: Allocator> From<Vec<T, A>> for Box<[T], A> {
-    /// Convert a vector into a boxed slice.
+    /// Converts a vector into [`Box<[T]>`][owned slice].
     ///
-    /// If `v` has excess capacity, its items will be moved into a
-    /// newly-allocated buffer with exactly the right capacity.
+    /// Before doing the conversion, this method discards excess capacity like [`Vec::shrink_to_fit`].
+    ///
+    /// [owned slice]: Box
+    /// [`Vec::shrink_to_fit`]: Vec::shrink_to_fit
     ///
     /// # Examples
     ///