From: Manish Goregaokar <manishsmail@gmail.com>
Date: Sun, 17 Apr 2016 12:20:33 +0000 (+0530)
Subject: Rollup merge of #31441 - gereeter:btree-docs, r=bluss
X-Git-Url: https://git.lizzy.rs/?a=commitdiff_plain;h=e59af6c7196ee0118c524e9d33df10419452698d;p=rust.git

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

Start documenting BTreeMap's node interface

cc @Gankro @apasel422
---

e59af6c7196ee0118c524e9d33df10419452698d
diff --cc src/libcollections/btree/node.rs
index 8ae23a646e4,0f54803da23..ad34de9e3df
--- a/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;