From 7b6eecf40e4c5319b96a55153e8bc28f0f6be8e6 Mon Sep 17 00:00:00 2001
From: Lilith Schier <lilith@naalunth.dev>
Date: Tue, 11 Aug 2026 19:04:17 +0200
Subject: [PATCH] commentary

---
 src/dice.rs | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/dice.rs b/src/dice.rs
index e1480ca..4914731 100644
--- a/src/dice.rs
+++ b/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()];