Add more docs

quinn-proto/src/connection/streams/mod.rs

@@ -351,13 +351,15 @@ fn push_pending(pending: &mut BTreeMap<PendingPriority, StreamId>, id: StreamId,
         }),
     ));
 
-    pending.insert(
-        PendingPriority {
-            priority,
-            recency: range.next().map(|(p, _)| p.recency - 1).unwrap_or(u64::MAX),
-        },
-        id,
-    );
+    // Determine the recency value for this stream
+    // Setting it to 1 below all preexisting streams of this priority causes it to be sorted after all of those streams in
+    // the `BTreeMap`. This implements round-robin scheduling for streams that are still pending even after being handled,
+    // as in that case they are removed and then immediately reinserted.
+    // If this is the only/first stream for this priority, recency is initialised to u64::MAX instead. As this function is
+    // the only place that recency is initialised or mutated, this ensures that it will practically never underflow.
+    let recency = range.next().map(|(p, _)| p.recency - 1).unwrap_or(u64::MAX);
+
+    pending.insert(PendingPriority { priority, recency }, id);
 }
 
 /// Key type for a [`BTreeMap`] for streams with pending data, to sort them by priority and recency