From f1b48b9bae09f6c75b4c7642506030503ed1aa1d Mon Sep 17 00:00:00 2001
From: Stein Somers <git@steinsomers.be>
Date: Fri, 14 Jan 2022 20:28:04 +0100
Subject: [PATCH] Improve the documentation of drain members

---
 library/alloc/src/collections/binary_heap.rs   |  2 +-
 library/alloc/src/collections/vec_deque/mod.rs | 17 ++++++++---------
 library/alloc/src/string.rs                    |  9 +++------
 library/alloc/src/vec/mod.rs                   | 15 ++++++++-------
 library/std/src/collections/hash/set.rs        |  2 +-
 5 files changed, 21 insertions(+), 24 deletions(-)

diff --git a/library/alloc/src/collections/binary_heap.rs b/library/alloc/src/collections/binary_heap.rs
index 56a4700181199..4689a7903bed3 100644
--- a/library/alloc/src/collections/binary_heap.rs
+++ b/library/alloc/src/collections/binary_heap.rs
@@ -748,7 +748,7 @@ impl<T: Ord> BinaryHeap<T> {
 
     /// Returns an iterator which retrieves elements in heap order.
     /// The retrieved elements are removed from the original heap.
-    /// The remaining elements will be removed on drop in heap order.
+    /// On drop, the remaining elements are removed and dropped in heap order.
     ///
     /// Note:
     /// * `.drain_sorted()` is *O*(*n* \* log(*n*)); much slower than `.drain()`.
diff --git a/library/alloc/src/collections/vec_deque/mod.rs b/library/alloc/src/collections/vec_deque/mod.rs
index a8a18d655855e..b347608c3ac20 100644
--- a/library/alloc/src/collections/vec_deque/mod.rs
+++ b/library/alloc/src/collections/vec_deque/mod.rs
@@ -1215,15 +1215,14 @@ impl<T, A: Allocator> VecDeque<T, A> {
         unsafe { IterMut::new(ring, tail, head, PhantomData) }
     }
 
-    /// Creates a draining iterator that removes the specified range in the
-    /// `VecDeque` and yields the removed items.
+    /// Removes the specified range from the `VecDeque`, returning all removed
+    /// elements as an iterator.
     ///
-    /// Note 1: The element range is removed even if the iterator is not
-    /// consumed until the end.
-    ///
-    /// Note 2: It is unspecified how many elements are removed from the deque,
-    /// if the `Drain` value is not dropped, but the borrow it holds expires
-    /// (e.g., due to `mem::forget`).
+    /// When the iterator **is** dropped, it drops any elements that it has not
+    /// yet yielded (none if the iterator was fully consumed).
+    /// If the iterator **is not** dropped (with [`mem::forget`], for example),
+    /// it is unspecified which elements remain in the vector; even elements
+    /// outside the range may have been removed and leaked.
     ///
     /// # Panics
     ///
@@ -1240,7 +1239,7 @@ impl<T, A: Allocator> VecDeque<T, A> {
     /// assert_eq!(drained, [3]);
     /// assert_eq!(v, [1, 2]);
     ///
-    /// // A full range clears all contents
+    /// // A full range clears all contents, like `clear()` does
     /// v.drain(..);
     /// assert!(v.is_empty());
     /// ```
diff --git a/library/alloc/src/string.rs b/library/alloc/src/string.rs
index 7c0faf0659a2c..9535f8963cdbf 100644
--- a/library/alloc/src/string.rs
+++ b/library/alloc/src/string.rs
@@ -1628,11 +1628,8 @@ impl String {
         self.vec.clear()
     }
 
-    /// Creates a draining iterator that removes the specified range in the `String`
-    /// and yields the removed `chars`.
-    ///
-    /// Note: The element range is removed even if the iterator is not
-    /// consumed until the end.
+    /// Removes the specified range from the string, returning all removed
+    /// characters as an iterator.
     ///
     /// # Panics
     ///
@@ -1652,7 +1649,7 @@ impl String {
     /// assert_eq!(t, "α is alpha, ");
     /// assert_eq!(s, "β is beta");
     ///
-    /// // A full range clears the string
+    /// // A full range clears the string, like `clear()` does
     /// s.drain(..);
     /// assert_eq!(s, "");
     /// ```
diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs
index bd3262b51d480..608016d088518 100644
--- a/library/alloc/src/vec/mod.rs
+++ b/library/alloc/src/vec/mod.rs
@@ -1799,13 +1799,14 @@ impl<T, A: Allocator> Vec<T, A> {
         self.len += count;
     }
 
-    /// Creates a draining iterator that removes the specified range in the vector
-    /// and yields the removed items.
+    /// Removes the specified range from the vector, returning all removed
+    /// elements as an iterator.
     ///
-    /// When the iterator **is** dropped, all elements in the range are removed
-    /// from the vector, even if the iterator was not fully consumed. If the
-    /// iterator **is not** dropped (with [`mem::forget`] for example), it is
-    /// unspecified how many elements are removed.
+    /// When the iterator **is** dropped, it drops any elements that it has not
+    /// yet yielded (none if the iterator was fully consumed).
+    /// If the iterator **is not** dropped (with [`mem::forget`], for example),
+    /// it is unspecified which elements remain in the vector; even elements
+    /// outside the range may have been removed and leaked.
     ///
     /// # Panics
     ///
@@ -1820,7 +1821,7 @@ impl<T, A: Allocator> Vec<T, A> {
     /// assert_eq!(v, &[1]);
     /// assert_eq!(u, &[2, 3]);
     ///
-    /// // A full range clears the vector
+    /// // A full range clears the vector, like `clear()` does
     /// v.drain(..);
     /// assert_eq!(v, &[]);
     /// ```
diff --git a/library/std/src/collections/hash/set.rs b/library/std/src/collections/hash/set.rs
index d1450987e7374..a7af8c5a2e4b6 100644
--- a/library/std/src/collections/hash/set.rs
+++ b/library/std/src/collections/hash/set.rs
@@ -227,7 +227,7 @@ impl<T, S> HashSet<T, S> {
         self.base.is_empty()
     }
 
-    /// Clears the set, returning all elements in an iterator.
+    /// Clears the set, returning all elements as an iterator.
     ///
     /// # Examples
     ///