docs: stack is ordered in ascending order. Added an example
@@ -481,11 +481,15 @@ impl<N: NodeInfo> TreeBuilder<N> {
/// Add leaves to accumulating tree.
///
- /// Creates a height sorted stack of nodes first.
- /// Given this stack, it pushes the nodes in descending height.
- /// This method is amortized O(n) where n is the size of the accumulating tree.
- /// The worst case: there is one node for which the call to `push` is the worst case scenario
- /// and the all the other nodes can be added without in constant time
+ /// Creates a stack of node lists, where all the nodes in a list have uniform node height.
+ /// The stack is height sorted in ascending order.
+ /// The length of any list in the stack is at most MAX_CHILDREN -1.
+ ///
+ /// Example of this kind of stack if MAX_CHILDREN = 3:
+ /// let n_i be some node of height i. Let the front of the array represent the top of the stack.
+ /// [[n_1, n_1], [n_2], [n_3, n_3]]
+ ///
+ /// The nodes in the stack are pushed on the accumulating tree one by one in the end.
pub fn push_leaves(&mut self, leaves: Vec<N::L>) {
let mut stack: Vec<Vec<Node<N>>> = Vec::new();
for leaf in leaves {
