Prune commentary and stale Rust port notes

core/src/util/dirty.rs

@@ -1,19 +1,5 @@
-//! Which entries of a GPU-bound array changed since the last upload.
-
 use std::ops::Range;
 
-/// A bitset of dirty entries, coalesced into a handful of ranges when it
-/// is time to upload.
-///
-/// **Why a bitset** rather than the two obvious alternatives, both of
-/// which were measured against the bench fixture before this was written
-/// (`scripts/rigs/ui-profile`'s `arena_churn`). A `min..max` span is far
-/// too coarse: a frame's changes land in 5-20 runs scattered across the
-/// whole arena, so the span is very nearly the whole buffer. A `Vec` of
-/// touched indices is too expensive to *write*: a streaming frame marks
-/// several thousand entries, which would mean an allocation and a sort
-/// per frame. Marking a bit is O(1), allocation-free and idempotent, and
-/// the scan that reads it back is one word per 64 entries.
 #[derive(Default)]
 pub struct Dirty {
     words: Vec<u64>,
@@ -26,7 +12,6 @@ pub struct Dirty {
 }
 
 impl Dirty {
-    /// Nothing uploaded yet, so nothing may be assumed about the buffer.
     pub fn new_all() -> Self {
         Self {
             words: Vec::new(),
@@ -76,14 +61,6 @@ impl Dirty {
         !self.all && self.words.iter().all(|w| *w == 0)
     }
 
-    /// The ranges to upload, in ascending order, merging two runs
-    /// separated by a gap of fewer than `gap` entries.
-    ///
-    /// Merging trades bytes for `write_buffer` calls, and the fixture
-    /// says the trade is very cheap in one direction: over a fling, a
-    /// 1 KiB gap costs 0.1% more bytes than merging nothing at all and
-    /// halves the worst-case call count (23 to 13). Past that it stops
-    /// paying -- 4 KiB is +2% bytes for two fewer calls.
     pub fn ranges(&self, len: usize, gap: usize) -> Vec<Range<usize>> {
         if self.all {
             return Vec::from_iter((len > 0).then_some(0..len));
@@ -93,15 +70,12 @@ impl Dirty {
             let mut bits = *word;
             while bits != 0 {
                 let start = w * 64 + bits.trailing_zeros() as usize;
-                // The run of set bits starting here, within this word.
                 let run = (bits >> (start - w * 64)).trailing_ones() as usize;
                 let end = (start + run).min(len);
                 if start >= len {
                     break;
                 }
                 match ranges.last_mut() {
-                    // `start - last.end` is the gap; equal ends means
-                    // adjacent, which always merges.
                     Some(last) if start - last.end <= gap => last.end = end,
                     _ => ranges.push(start..end),
                 }
@@ -158,8 +132,6 @@ mod tests {
 
     #[test]
     fn ranges_stop_at_the_length() {
-        // Entries marked and then dropped by a shrink must not be
-        // uploaded past the end of what the caller is writing.
         assert_eq!(marked(&[1, 2, 40], 3, 0), vec![1..3]);
     }