diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs
index ede1601fa33cc..98abdfe09c428 100644
--- a/library/alloc/src/vec/mod.rs
+++ b/library/alloc/src/vec/mod.rs
@@ -1783,6 +1783,20 @@ impl<T, A: Allocator> Vec<T, A> {
     /// static_ref[0] += 1;
     /// assert_eq!(static_ref, &[2, 2, 3]);
     /// ```
+    ///
+    /// Drop excess capacity:
+    ///
+    /// ```
+    /// let mut v = Vec::with_capacity(10);
+    /// v.extend([1, 2, 3].iter().cloned());
+    /// let slice = v.clone().into_boxed_slice();
+    ///
+    /// unsafe {
+    ///     let p = slice.as_ptr();
+    ///     let rebuilt = std::slice::from_raw_parts(p, slice.len());
+    ///     assert_eq!(rebuilt.len(), 3);
+    /// }
+    /// ```
     #[stable(feature = "vec_leak", since = "1.47.0")]
     #[inline]
     pub fn leak<'a>(self) -> &'a mut [T]