commentary

src/dice.rs

@@ -99,6 +99,8 @@ impl Expression {
                 let mut rolls = (0..count)
                     .map(|_| rng.random_range(1..=size))
                     .collect::<Vec<_>>();
+
+                // Exploding dice are early, they add rolls
                 if let Some(fragments) = x {
                     write!(writer, "x")?;
                     if size < 2 {
@@ -129,6 +131,7 @@ impl Expression {
                     }
                 }
 
+                // Advantage/disadvantage roll filters
                 let kh = if let Some(child) = kh {
                     write!(writer, "kh")?;
                     Some(child.evaluate(rng, writer, precedence)? as usize)
@@ -154,6 +157,9 @@ impl Expression {
                     None
                 };
 
+                // Don't sort the rolls directly, to preserve their original order for other logic
+                // instead, `ranks` contains the indices where they would be in the array,
+                // if it was sorted.
                 let mut sorted_rolls = (0..rolls.len()).collect::<Vec<_>>();
                 sorted_rolls.sort_by_key(|idx| rolls[*idx]);
                 let mut ranks = vec![0usize; sorted_rolls.len()];