Rollup merge of rust-lang#103482 - aDotInTheVoid:vec-cap-docs, r=thomcc

Clairify Vec::capacity docs

Update both the text and example to be clear that the method gives *total*, (not *spare*) capacity

Fixes rust-lang#103326

Author: Dylan-DPC

library/alloc/src/vec/mod.rs

@@ -868,13 +868,14 @@ impl<T, A: Allocator> Vec<T, A> {
         (ptr, len, capacity, alloc)
     }
 
-    /// Returns the number of elements the vector can hold without
+    /// Returns the total number of elements the vector can hold without
     /// reallocating.
     ///
     /// # Examples
     ///
     /// ```
-    /// let vec: Vec<i32> = Vec::with_capacity(10);
+    /// let mut vec: Vec<i32> = Vec::with_capacity(10);
+    /// vec.push(42);
     /// assert_eq!(vec.capacity(), 10);
     /// ```
     #[inline]