document & clarify is_descendant_pos

src/helper.rs

@@ -75,8 +75,12 @@ pub fn get_peak_map(mmr_size: u64) -> u64 {
     peak_map
 }
 
+/// Returns whether `descendant_contender` is a descendant of `ancestor_contender` in a tree of the MMR.
 pub fn is_descendant_pos(ancestor_contender: u64, descendant_contender: u64) -> bool {
+    // NOTE: "ancestry" here refers to the hierarchy within an MMR tree, not temporal hierarchy.
+    // the descendant needs to have been added to the mmr prior to the ancestor
     descendant_contender <= ancestor_contender
+        // the descendant needs to be within the cone of positions descendant from the ancestor
         && descendant_contender
             >= (ancestor_contender + 1 - sibling_offset(pos_height_in_tree(ancestor_contender)))
 }