Auto merge of #94148 - matthiaskrgr:rollup-jgea68f, r=matthiaskrgr

Rollup of 7 pull requests

Successful merges:

 - #92902 (Improve the documentation of drain members)
 - #93658 (Stabilize `#[cfg(panic = "...")]`)
 - #93954 (rustdoc-json: buffer output)
 - #93979 (Add debug assertions to validate NUL terminator in c strings)
 - #93990 (pre #89862 cleanup)
 - #94006 (Use a `Field` in `ConstraintCategory::ClosureUpvar`)
 - #94086 (Fix ScalarInt to char conversion)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup

1 files changed, 11 insertions, 5 deletions

diff --git a/library/alloc/src/collections/binary_heap.rs b/library/alloc/src/collections/binary_heap.rs
index 56a47001811..e18cd8cd464 100644
--- a/library/alloc/src/collections/binary_heap.rs
+++ b/library/alloc/src/collections/binary_heap.rs
@@ -746,9 +746,12 @@ impl<T: Ord> BinaryHeap<T> {
         self.rebuild_tail(start);
     }
 
-    /// 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.
+    /// Clears the binary heap, returning an iterator over the removed elements
+    /// in heap order. If the iterator is dropped before being fully consumed,
+    /// it drops the remaining elements in heap order.
+    ///
+    /// The returned iterator keeps a mutable borrow on the heap to optimize
+    /// its implementation.
     ///
     /// Note:
     /// * `.drain_sorted()` is *O*(*n* \* log(*n*)); much slower than `.drain()`.
@@ -1158,9 +1161,12 @@ impl<T> BinaryHeap<T> {
         self.len() == 0
     }
 
-    /// Clears the binary heap, returning an iterator over the removed elements.
+    /// Clears the binary heap, returning an iterator over the removed elements
+    /// in arbitrary order. If the iterator is dropped before being fully
+    /// consumed, it drops the remaining elements in arbitrary order.
     ///
-    /// The elements are removed in arbitrary order.
+    /// The returned iterator keeps a mutable borrow on the heap to optimize
+    /// its implementation.
     ///
     /// # Examples
     ///