docs(vec): clarify into_boxed_slice allocation guarantee

library/alloc/src/boxed/convert.rs

@@ -286,13 +286,14 @@ impl<T, const N: usize, A: Allocator> TryFrom<Vec<T, A>> for Box<[T; N], A> {
 
     /// Attempts to convert a `Vec<T>` into a `Box<[T; N]>`.
     ///
-    /// Like [`Vec::into_boxed_slice`], this is in-place if `vec.capacity() == N`,
-    /// but will require a reallocation otherwise.
+    /// Like [`Vec::into_boxed_slice`], this is in-place if `vec.capacity() == N`
+    /// and `vec.len() == N`. If the `vec.len() == N` but there is spare capacity,
+    /// the allocation will be either shrunk or reallocated.
     ///
     /// # Errors
     ///
     /// Returns the original `Vec<T>` in the `Err` variant if
-    /// `boxed_slice.len()` does not equal `N`.
+    /// `vec.len()` does not equal `N`.
     ///
     /// # Examples
     ///

library/alloc/src/vec/mod.rs

@@ -1688,10 +1688,13 @@ impl<T, A: Allocator> Vec<T, A> {
 
     /// Converts the vector into [`Box<[T]>`][owned slice].
     ///
-    /// Before doing the conversion, this method discards excess capacity like [`shrink_to_fit`].
+    /// Before doing the conversion, this method adjusts the vector's allocation as
+    /// needed so that, if a backing allocation is present, the layout of the returned
+    /// slice [*fits*] that allocation. Thus, the vector's former capacity is not needed
+    /// to determine a layout suitable for deallocation.
     ///
     /// [owned slice]: Box
-    /// [`shrink_to_fit`]: Vec::shrink_to_fit
+    /// [*fits*]: crate::alloc::Allocator#memory-fitting
     ///
     /// # Examples
     ///
@@ -1701,7 +1704,7 @@ impl<T, A: Allocator> Vec<T, A> {
     /// let slice = v.into_boxed_slice();
     /// ```
     ///
-    /// Any excess capacity is removed:
+    /// The vector's spare capacity is not retained:
     ///
     /// ```
     /// let mut vec = Vec::with_capacity(10);
@@ -1725,7 +1728,7 @@ impl<T, A: Allocator> Vec<T, A> {
     }
 
     /// Converts the Vec into a boxed array. This conversion will discard any spare capacity,
-    /// if there is any, see [`Vec::shrink_to_fit`].
+    /// if there is any, see [`Vec::into_boxed_slice`].
     /// If you merely wish for a reference to an array, use [`as_array`](https://doc.rust-lang.org/stable/std/primitive.slice.html#method.as_array).
     ///
     /// # Errors
@@ -4543,7 +4546,6 @@ where
     }
 }
 
-// note: test pulls in std, which causes errors here
 #[stable(feature = "vec_from_box", since = "1.18.0")]
 impl<T, A: Allocator> From<Box<[T], A>> for Vec<T, A> {
     /// Converts a boxed slice into a vector by transferring ownership of
@@ -4560,30 +4562,18 @@ impl<T, A: Allocator> From<Box<[T], A>> for Vec<T, A> {
     }
 }
 
-// note: test pulls in std, which causes errors here
 #[cfg(not(no_global_oom_handling))]
 #[stable(feature = "box_from_vec", since = "1.20.0")]
 impl<T, A: Allocator> From<Vec<T, A>> for Box<[T], A> {
     /// Converts a vector into a boxed slice.
     ///
-    /// 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
+    /// This is equivalent to [`Vec::into_boxed_slice`].
     ///
     /// # Examples
     ///
     /// ```
     /// assert_eq!(Box::from(vec![1, 2, 3]), vec![1, 2, 3].into_boxed_slice());
     /// ```
-    ///
-    /// Any excess capacity is removed:
-    /// ```
-    /// let mut vec = Vec::with_capacity(10);
-    /// vec.extend([1, 2, 3]);
-    ///
-    /// assert_eq!(Box::from(vec), vec![1, 2, 3].into_boxed_slice());
-    /// ```
     fn from(v: Vec<T, A>) -> Self {
         v.into_boxed_slice()
     }