Rollup merge of #39701 - sgrif:sg-vec-reserve-docs, r=alexcrichton

Explicitly mention that `Vec::reserve` is based on len not capacity

I spent a good chunk of time tracking down a buffer overrun bug that
resulted from me mistakenly thinking that `reserve` was based on the
current capacity not the current length. It would be helpful if this
were called out explicitly in the docs.

1 files changed, 6 insertions, 3 deletions

diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs
index dc0f33d9bc3..3873b3535a0 100644
--- a/src/libcollections/vec.rs
+++ b/src/libcollections/vec.rs
@@ -437,7 +437,9 @@ impl<T> Vec<T> {
 
     /// Reserves capacity for at least `additional` more elements to be inserted
     /// in the given `Vec<T>`. The collection may reserve more space to avoid
-    /// frequent reallocations.
+    /// frequent reallocations. After calling `reserve`, capacity will be
+    /// greater than or equal to `self.len() + additional`. Does nothing if
+    /// capacity is already sufficient.
     ///
     /// # Panics
     ///
@@ -456,8 +458,9 @@ impl<T> Vec<T> {
     }
 
     /// Reserves the minimum capacity for exactly `additional` more elements to
-    /// be inserted in the given `Vec<T>`. Does nothing if the capacity is already
-    /// sufficient.
+    /// be inserted in the given `Vec<T>`. After calling `reserve_exact`,
+    /// capacity will be greater than or equal to `self.len() + additional`.
+    /// Does nothing if the capacity is already sufficient.
     ///
     /// Note that the allocator may give the collection more space than it
     /// requests. Therefore capacity can not be relied upon to be precisely