Rollup merge of #31441 - gereeter:btree-docs, r=bluss

Start documenting BTreeMap's node interface

cc @Gankro @apasel422

diff --cc src/libcollections/btree/node.rs
index 8ae23a646e48855caa7ed93019d42d6e8bcc060b,0f54803da23a838e589c3bbea6a01456d991101f..ad34de9e3df97b2b9a954785010ee797dab87eb3
--- 1/src/libcollections/btree/node.rs
--- 2/src/libcollections/btree/node.rs
+++ b/src/libcollections/btree/node.rs
@@@ -28,9 -28,19 +28,19 @@@
  // }
  // ```
  //
 -// Since Rust doesn't acutally have dependent types and polymorphic recursion,
 +// Since Rust doesn't actually have dependent types and polymorphic recursion,
  // we make do with lots of unsafety.
  
+ // A major goal of this module is to avoid complexity by treating the tree as a generic (if
+ // weirdly shaped) container and avoiding dealing with most of the B-Tree invariants. As such,
+ // this module doesn't care whether the entries are sorted, which nodes can be underfull, or
+ // even what underfull means. However, we do rely on a few invariants:
+ //
+ // - Trees must have uniform depth/height. This means that every path down to a leaf from a
+ //   given node has exactly the same length.
+ // - A node of length `n` has `n` keys, `n` values, and (in an internal node) `n + 1` edges.
+ //   This implies that even an empty internal node has at least one edge.
+ 
  use alloc::heap;
  use core::marker::PhantomData;
  use core::mem;