Rollup merge of rust-lang#87679 - ssomers:btree_comments, r=joshtriplett

BTree: refine some comments

library/alloc/src/collections/btree/map.rs

@@ -19,16 +19,16 @@ mod entry;
 pub use entry::{Entry, OccupiedEntry, OccupiedError, VacantEntry};
 use Entry::*;
 
-/// Minimum number of elements in nodes that are not a root.
+/// Minimum number of elements in a node that is not a root.
 /// We might temporarily have fewer elements during methods.
 pub(super) const MIN_LEN: usize = node::MIN_LEN_AFTER_SPLIT;
 
 // A tree in a `BTreeMap` is a tree in the `node` module with additional invariants:
 // - Keys must appear in ascending order (according to the key's type).
-// - If the root node is internal, it must contain at least 1 element.
+// - Every non-leaf node contains at least 1 element (has at least 2 children).
 // - Every non-root node contains at least MIN_LEN elements.
 //
-// An empty map may be represented both by the absence of a root node or by a
+// An empty map is represented either by the absence of a root node or by a
 // root node that is an empty leaf.
 
 /// A map based on a [B-Tree].
@@ -1735,8 +1735,8 @@ impl<'a, K: 'a, V: 'a> DrainFilterInner<'a, K, V> {
     pub(super) fn size_hint(&self) -> (usize, Option<usize>) {
         // In most of the btree iterators, `self.length` is the number of elements
         // yet to be visited. Here, it includes elements that were visited and that
-        // the predicate decided not to drain. Making this upper bound more accurate
-        // requires maintaining an extra field and is not worth while.
+        // the predicate decided not to drain. Making this upper bound more tight
+        // during iteration would require an extra field.
         (0, Some(*self.length))
     }
 }

library/alloc/src/collections/btree/navigate.rs

@@ -440,8 +440,7 @@ impl<K, V> Handle<NodeRef<marker::Dying, K, V, marker::Leaf>, marker::Edge> {
     /// - The given edge must not have been previously returned by counterpart
     ///   `deallocating_next_back`.
     /// - The returned KV handle is only valid to access the key and value,
-    ///   and only valid until the next call to this method or counterpart
-    ///   `deallocating_next_back`.
+    ///   and only valid until the next call to a `deallocating_` method.
     unsafe fn deallocating_next(
         self,
     ) -> Option<(Self, Handle<NodeRef<marker::Dying, K, V, marker::LeafOrInternal>, marker::KV>)>
@@ -470,8 +469,7 @@ impl<K, V> Handle<NodeRef<marker::Dying, K, V, marker::Leaf>, marker::Edge> {
     /// - The given edge must not have been previously returned by counterpart
     ///   `deallocating_next`.
     /// - The returned KV handle is only valid to access the key and value,
-    ///   and only valid until the next call to this method or counterpart
-    ///   `deallocating_next`.
+    ///   and only valid until the next call to a `deallocating_` method.
     unsafe fn deallocating_next_back(
         self,
     ) -> Option<(Self, Handle<NodeRef<marker::Dying, K, V, marker::LeafOrInternal>, marker::KV>)>

library/alloc/src/collections/btree/node.rs

@@ -574,7 +574,7 @@ impl<K, V> NodeRef<marker::Owned, K, V, marker::LeafOrInternal> {
     /// no cleanup is done on any of the keys, values and other children.
     /// This decreases the height by 1 and is the opposite of `push_internal_level`.
     ///
-    /// Requires exclusive access to the `Root` object but not to the root node;
+    /// Requires exclusive access to the `NodeRef` object but not to the root node;
     /// it will not invalidate other handles or references to the root node.
     ///
     /// Panics if there is no internal level, i.e., if the root node is a leaf.