Perhaps improve the documentation of drain members further

Author: ssomers

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:

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:

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),

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`]

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: