From 8fa032a7391fa160138a6c53ec4c031850493b69 Mon Sep 17 00:00:00 2001
From: Stein Somers <git@steinsomers.be>
Date: Tue, 8 Feb 2022 11:44:34 +0100
Subject: [PATCH] Perhaps improve the documentation of drain members further

---
 library/alloc/src/collections/binary_heap.rs   | 14 ++++++++++++++
 library/alloc/src/collections/linked_list.rs   |  8 ++++++++
 library/alloc/src/collections/vec_deque/mod.rs |  2 ++
 library/alloc/src/string.rs                    |  5 +++++
 library/alloc/src/vec/mod.rs                   | 10 ++++++++++
 5 files changed, 39 insertions(+)

diff --git a/library/alloc/src/collections/binary_heap.rs b/library/alloc/src/collections/binary_heap.rs
index 4689a7903bed3..e90e87d4685ad 100644
--- a/library/alloc/src/collections/binary_heap.rs
+++ b/library/alloc/src/collections/binary_heap.rs
@@ -754,6 +754,12 @@ impl<T: Ord> BinaryHeap<T> {
     /// * `.drain_sorted()` is *O*(*n* \* log(*n*)); much slower than `.drain()`.
     ///   You should use the latter for most cases.
     ///
+    /// # Leaking
+    ///
+    /// In case the iterator disappears without getting dropped (using
+    /// [`mem::forget`], for example), it is unspecified whether the
+    /// remaining elements are still in the heap or leaked.
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -1162,6 +1168,14 @@ impl<T> BinaryHeap<T> {
     ///
     /// The elements are removed in arbitrary order.
     ///
+    /// # Leaking
+    ///
+    /// 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 whether the elements not yet yielded are still in the
+    /// heap or leaked.
+    ///
     /// # Examples
     ///
     /// Basic usage:
diff --git a/library/alloc/src/collections/linked_list.rs b/library/alloc/src/collections/linked_list.rs
index 4a07d5d4bed10..998a82b2b9b15 100644
--- a/library/alloc/src/collections/linked_list.rs
+++ b/library/alloc/src/collections/linked_list.rs
@@ -970,6 +970,14 @@ impl<T> LinkedList<T> {
     /// Note that `drain_filter` lets you mutate every element in the filter closure, regardless of
     /// whether you choose to keep or remove it.
     ///
+    /// # Leaking
+    ///
+    /// When the iterator **is** dropped, it drops any elements that it has not
+    /// yet yielded and for which the closure returns true.
+    /// If the iterator **is not** dropped (with [`mem::forget`], for example),
+    /// it is unspecified whether the elements not yet yielded are still in the
+    /// list or leaked.
+    ///
     /// # Examples
     ///
     /// Splitting a list into evens and odds, reusing the original list:
diff --git a/library/alloc/src/collections/vec_deque/mod.rs b/library/alloc/src/collections/vec_deque/mod.rs
index b347608c3ac20..8b43576f968b2 100644
--- a/library/alloc/src/collections/vec_deque/mod.rs
+++ b/library/alloc/src/collections/vec_deque/mod.rs
@@ -1218,6 +1218,8 @@ impl<T, A: Allocator> VecDeque<T, A> {
     /// Removes the specified range from the `VecDeque`, returning all removed
     /// elements as an iterator.
     ///
+    /// # Leaking
+    ///
     /// 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),
diff --git a/library/alloc/src/string.rs b/library/alloc/src/string.rs
index 9535f8963cdbf..b3ed79aaa402c 100644
--- a/library/alloc/src/string.rs
+++ b/library/alloc/src/string.rs
@@ -1631,6 +1631,11 @@ impl String {
     /// Removes the specified range from the string, returning all removed
     /// characters as an iterator.
     ///
+    /// # Leaking
+    ///
+    /// In case the iterator disappears without getting dropped (using
+    /// [`core::mem::forget`], for example), the range remains in the string.
+    ///
     /// # Panics
     ///
     /// Panics if the starting point or end point do not lie on a [`char`]
diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs
index 608016d088518..6876166560a3f 100644
--- a/library/alloc/src/vec/mod.rs
+++ b/library/alloc/src/vec/mod.rs
@@ -1802,6 +1802,8 @@ impl<T, A: Allocator> Vec<T, A> {
     /// Removes the specified range from the vector, returning all removed
     /// elements as an iterator.
     ///
+    /// # Leaking
+    ///
     /// 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),
@@ -2732,6 +2734,14 @@ impl<T, A: Allocator> Vec<T, A> {
     /// Note that `drain_filter` also lets you mutate every element in the filter closure,
     /// regardless of whether you choose to keep or remove it.
     ///
+    /// # Leaking
+    ///
+    /// When the iterator **is** dropped, it drops any elements that it has not
+    /// yet yielded and for which the closure returns true.
+    /// 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.
+    ///
     /// # Examples
     ///
     /// Splitting an array into evens and odds, reusing the original allocation: