BTreeMap: try to enhance various comments

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

@@ -459,7 +459,7 @@ impl<'a, K: Ord, V> OccupiedEntry<'a, K, V> {
         self.remove_kv().1
     }
 
-    // Body of `remove_entry`, separate to keep the above implementations short.
+    // Body of `remove_entry`, probably separate because the name reflects the returned pair.
     pub(super) fn remove_kv(self) -> (K, V) {
         let mut emptied_internal_root = false;
         let (old_kv, _) = self.handle.remove_kv_tracking(|| emptied_internal_root = true);

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

@@ -9,6 +9,9 @@ use super::search::{self, SearchResult};
 use super::unwrap_unchecked;
 
 /// Finds the leaf edges delimiting a specified range in or underneath a node.
+///
+/// The result is meaningful only if the tree is ordered by key, like the tree
+/// in a `BTreeMap` is.
 fn range_search<BorrowType, K, V, Q, R>(
     root1: NodeRef<BorrowType, K, V, marker::LeafOrInternal>,
     root2: NodeRef<BorrowType, K, V, marker::LeafOrInternal>,
@@ -122,6 +125,9 @@ fn full_range<BorrowType, K, V>(
 
 impl<'a, K: 'a, V: 'a> NodeRef<marker::Immut<'a>, K, V, marker::LeafOrInternal> {
     /// Creates a pair of leaf edges delimiting a specified range in or underneath a node.
+    ///
+    /// The result is meaningful only if the tree is ordered by key, like the tree
+    /// in a `BTreeMap` is.
     pub fn range_search<Q, R>(
         self,
         range: R,
@@ -152,6 +158,9 @@ impl<'a, K: 'a, V: 'a> NodeRef<marker::ValMut<'a>, K, V, marker::LeafOrInternal>
     /// Splits a unique reference into a pair of leaf edges delimiting a specified range.
     /// The result are non-unique references allowing (some) mutation, which must be used
     /// carefully.
+    ///
+    /// The result is meaningful only if the tree is ordered by key, like the tree
+    /// in a `BTreeMap` is.
     pub fn range_search<Q, R>(
         self,
         range: R,

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

@@ -4,7 +4,7 @@ use super::unwrap_unchecked;
 use core::mem;
 
 impl<'a, K: 'a, V: 'a> Handle<NodeRef<marker::Mut<'a>, K, V, marker::LeafOrInternal>, marker::KV> {
-    /// Removes a key/value-pair from the tree, and returns that pair, as well as
+    /// Removes a key-value pair from the tree, and returns that pair, as well as
     /// the leaf edge corresponding to that former pair. It's possible this empties
     /// a root node that is internal, which the caller should pop from the map
     /// holding the tree. The caller should also decrement the map's length.

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

@@ -14,6 +14,9 @@ pub enum SearchResult<BorrowType, K, V, FoundType, GoDownType> {
 /// Returns a `Found` with the handle of the matching KV, if any. Otherwise,
 /// returns a `GoDown` with the handle of the possible leaf edge where the key
 /// belongs.
+///
+/// The result is meaningful only if the tree is ordered by key, like the tree
+/// in a `BTreeMap` is.
 pub fn search_tree<BorrowType, K, V, Q: ?Sized>(
     mut node: NodeRef<BorrowType, K, V, marker::LeafOrInternal>,
     key: &Q,
@@ -38,8 +41,11 @@ where
 
 /// Looks up a given key in a given node, without recursion.
 /// Returns a `Found` with the handle of the matching KV, if any. Otherwise,
-/// returns a `GoDown` with the handle of the edge where the key might be found.
-/// If the node is a leaf, a `GoDown` edge is not an actual edge but a possible edge.
+/// returns a `GoDown` with the handle of the edge where the key might be found
+/// (if the node is internal) or where the key can be inserted.
+///
+/// The result is meaningful only if the tree is ordered by key, like the tree
+/// in a `BTreeMap` is.
 pub fn search_node<BorrowType, K, V, Type, Q: ?Sized>(
     node: NodeRef<BorrowType, K, V, Type>,
     key: &Q,
@@ -54,11 +60,11 @@ where
     }
 }
 
-/// Returns the index in the node at which the key (or an equivalent) exists
-/// or could exist, and whether it exists in the node itself. If it doesn't
-/// exist in the node itself, it may exist in the subtree with that index
-/// (if the node has subtrees). If the key doesn't exist in node or subtree,
-/// the returned index is the position or subtree where the key belongs.
+/// Returns either the KV index in the node at which the key (or an equivalent)
+/// exists and `true`, or the edge index where the key belongs and `false`.
+///
+/// The result is meaningful only if the tree is ordered by key, like the tree
+/// in a `BTreeMap` is.
 fn search_linear<BorrowType, K, V, Type, Q: ?Sized>(
     node: &NodeRef<BorrowType, K, V, Type>,
     key: &Q,

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

@@ -214,7 +214,7 @@ impl<T: fmt::Debug> fmt::Debug for Union<'_, T> {
 // This constant is used by functions that compare two sets.
 // It estimates the relative size at which searching performs better
 // than iterating, based on the benchmarks in
-// https://github.com/ssomers/rust_bench_btreeset_intersection;
+// https://github.com/ssomers/rust_bench_btreeset_intersection.
 // It's used to divide rather than multiply sizes, to rule out overflow,
 // and it's a power of two to make that division cheap.
 const ITER_PERFORMANCE_TIPPING_SIZE_DIFF: usize = 16;

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

@@ -23,8 +23,8 @@ impl<K, V> Root<K, V> {
             loop {
                 let mut split_edge = match search_node(left_node, key) {
                     // key is going to the right tree
-                    Found(handle) => handle.left_edge(),
-                    GoDown(handle) => handle,
+                    Found(kv) => kv.left_edge(),
+                    GoDown(edge) => edge,
                 };
 
                 split_edge.move_suffix(&mut right_node);