Improve the documentation for Vec::drain

diff --git a/src/liballoc/vec.rs b/src/liballoc/vec.rs
index 5db96a504a6a69a1a72c1181464d92a5b7f40e12..269eeed3ccf8608ec0c2f9acb3656efead38c143 100644 (file)
--- 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