Tidied comments

Author: wainwrightmark

src/seq/increasing_uniform.rs

@@ -1,19 +1,22 @@
 use crate::{Rng, RngCore};
 
-/// Similar to a Uniform distribution, but after returning a number in the range [0,n], n is increased by 1.
+/// Similar to a Uniform distribution,
+/// but after returning a number in the range [0,n], n is increased by 1.
 pub(crate) struct IncreasingUniform<R: RngCore> {
     pub rng: R,
     n: u32,
-    //TODO(opt): this should depend on RNG word size
-    chunk: u32, //Chunk is a random number in [0, (n + 1) * (n + 2) *..* (n + chunk_remaining) )
+    // Chunk is a random number in [0, (n + 1) * (n + 2) *..* (n + chunk_remaining) )
+    chunk: u32,
     chunk_remaining: u8,
 }
 
 impl<R: RngCore> IncreasingUniform<R> {
     /// Create a dice roller.
     /// The next item returned will be a random number in the range [0,n]
     pub fn new(rng: R, n: u32) -> Self {
-        let chunk_remaining = if n == 0 { 1 } else { 0 }; // If n = 0, the first number returned will always be 0, so we don't need to generate a random number
+        // If n = 0, the first number returned will always be 0
+        // so we don't need to generate a random number
+        let chunk_remaining = if n == 0 { 1 } else { 0 };
         Self {
             rng,
             n,
@@ -30,22 +33,24 @@ impl<R: RngCore> IncreasingUniform<R> {
         let next_n = self.n + 1;
 
         let next_chunk_remaining = self.chunk_remaining.checked_sub(1).unwrap_or_else(|| {
-            //If the chunk is empty, generate a new chunk
+            // If the chunk is empty, generate a new chunk
             let (bound, remaining) = calculate_bound_u32(next_n);
-            //bound = (n + 1) * (n + 2) *..* (n + remaining)
+            // bound = (n + 1) * (n + 2) *..* (n + remaining)
             self.chunk = self.rng.gen_range(0..bound);
-            // Chunk is a random number in [0, (n + 1) * (n + 2) *..* (n + remaining) )
+            // Chunk is a random number in
+            // [0, (n + 1) * (n + 2) *..* (n + remaining) )
 
             remaining - 1
         });
 
         let result = if next_chunk_remaining == 0 {
-            //If the chunk is empty we asr
-            self.chunk as usize
             // `chunk` is a random number in the range [0..n+1)
-            // Because `chunk_remaining` is about to be set to zero, we do not need to clear the chunk here
+            // Because `chunk_remaining` is about to be set to zero
+            // we do not need to clear the chunk here
+            self.chunk as usize
         } else {
-            // `chunk` is a random number in a range that is a multiple of n+1 so r will be a random number in [0..n+1)
+            // `chunk` is a random number in a range that is a multiple of n+1
+            // so r will be a random number in [0..n+1)
             let r = self.chunk % next_n;
             self.chunk /= next_n;
             r as usize
@@ -70,15 +75,18 @@ fn calculate_bound_u32(m: u32) -> (u32, u8) {
                 product = p;
                 current += 1;
             } else {
-                let count = (current - m) as u8; //Maximum value of 13 for when min is 1 or 2
+                // Count has a maximum value of 13 for when min is 1 or 2
+                let count = (current - m) as u8;
                 return (product, count);
             }
         }
     }
 
     const RESULT2: (u32, u8) = inner(2);
     if m == 2 {
-        return RESULT2; //Making this value a constant instead of recalculating it gives a significant (~50%) performance boost for small shuffles
+        // Making this value a constant instead of recalculating it
+        // gives a significant (~50%) performance boost for small shuffles
+        return RESULT2;
     }
 
     inner(m)

src/seq/mod.rs

@@ -636,24 +636,12 @@ impl<T> SliceRandom for [T] {
         // The algorithm below is based on Durstenfeld's algorithm for the
         // [Fisher–Yates shuffle](https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#The_modern_algorithm)
         // for an unbiased permutation.
-        // It ensures that the last `amount` elements of the slice are randomly selected from the whole slice.
-
-        // The loop invariant is that elements in the range [m,i) are randomly selected from the first i elements.
-        // This is true initially because the range is empty as i = m.
-        // The loop body swaps the element at i with a random one of the first i + 1 elements, then increments i.
-        // After the swap, the element at i will be randomly selected from the first i + 1 elements.
-        // Because of the invariant, before the swap, every element in the range [m,i) was randomly selected from the first i elements.
-        // Each of those elements has a 1 in i chance of being swapped with the element at i.
-        // Therefore, after the swap, the elements in the range [m,i) will be randomly selected from the first i + 1 elements.
-        // But the element at i was also randomly selected from the first i + 1 elements.
-        // So the elements in the range [m,i+1) are all randomly selected from the first i + 1 elements.
-        // So before we increment i, the elements in the range [m,i + 1) are randomly selected from the first i + 1 elements.
-        // Therefore, the loop invariant holds.        
-        // When the loop exits, elements in the range [m,length] will be randomly selected from the whole slice.
+        // It ensures that the last `amount` elements of the slice
+        // are randomly selected from the whole slice.
 
-        
-        //`IncreasingUniform::next_index()` is about twice as fast as `gen_index` but only works for 32 bit integers
-        //Therefore we must use the slow method if the slice is longer than that.
+        //`IncreasingUniform::next_index()` is faster than `gen_index`
+        //but only works for 32 bit integers
+        //So we must use the slow method if the slice is longer than that.
         if self.len() < (u32::MAX as usize) {
             let mut chooser = IncreasingUniform::new(rng, m as u32);
             for i in m..self.len() {