From: Alexis Bourget <alexis.bourget@gmail.com>
Date: Wed, 22 Jul 2020 19:50:16 +0000 (+0200)
Subject: Improve the documentation for Vec::drain
X-Git-Url: https://git.lizzy.rs/?a=commitdiff_plain;h=e601e2ac48a217fafb5962a43680d60c574d35ef;p=rust.git

Improve the documentation for Vec::drain
---

diff --git a/src/liballoc/vec.rs b/src/liballoc/vec.rs
index 5db96a504a6..269eeed3ccf 100644
--- a/src/liballoc/vec.rs
+++ b/src/liballoc/vec.rs
@@ -1274,11 +1274,12 @@ unsafe fn append_elements(&mut self, other: *const [T]) {
     /// Creates a draining iterator that removes the specified range in the vector
     /// and yields the removed items.
     ///
-    /// Note 1: The element range is removed even if the iterator is only
-    /// partially consumed or not consumed at all.
+    /// The element range is removed even if the iterator is only partially
+    /// consumed or not consumed at all.
     ///
-    /// Note 2: It is unspecified how many elements are removed from the vector
-    /// if the `Drain` value is leaked.
+    /// Note: Be aware that if the iterator is leaked (eg: [`mem::forget`]), it
+    /// cancels this property so it is unspecified how many elements are removed
+    /// from the vector in this case.
     ///
     /// # Panics
     ///
@@ -1297,6 +1298,8 @@ unsafe fn append_elements(&mut self, other: *const [T]) {
     /// v.drain(..);
     /// assert_eq!(v, &[]);
     /// ```
+    ///
+    /// [`mem::forget`]: mem::forget
     #[stable(feature = "drain", since = "1.6.0")]
     pub fn drain<R>(&mut self, range: R) -> Drain<'_, T>
     where