Auto merge of #39738 - keeperofdakeys:vec-docs, r=GuillaumeGomez

Add notes about capacity effects to Vec::truncate()

Add notes about the effects of Vec::truncate() and Vec::clear() on the capacity of a vector.

src/libcollections/string.rs

@@ -999,6 +999,9 @@ pub fn as_bytes(&self) -> &[u8] {
     /// If `new_len` is greater than the string's current length, this has no
     /// effect.
     ///
+    /// Note that this method has no effect on the allocated capacity
+    /// of the string
+    ///
     /// # Panics
     ///
     /// Panics if `new_len` does not lie on a [`char`] boundary.

src/libcollections/vec.rs

@@ -548,6 +548,9 @@ pub fn into_boxed_slice(mut self) -> Box<[T]> {
     /// The [`drain`] method can emulate `truncate`, but causes the excess
     /// elements to be returned instead of dropped.
     ///
+    /// Note that this method has no effect on the allocated capacity
+    /// of the vector.
+    ///
     /// # Examples
     ///
     /// Truncating a five element vector to two elements:
@@ -1092,6 +1095,9 @@ pub fn drain<R>(&mut self, range: R) -> Drain<T>
 
     /// Clears the vector, removing all values.
     ///
+    /// Note that this method has no effect on the allocated capacity
+    /// of the vector.
+    ///
     /// # Examples
     ///
     /// ```