Improved the comments

Author: fizyk20

src/distributions/poisson.rs

@@ -58,8 +58,9 @@ impl Sample<u64> for Poisson {
 impl IndependentSample<u64> for Poisson {
     fn ind_sample<R: Rng>(&self, rng: &mut R) -> u64 {
         // using the algorithm from Numerical Recipes in C
+
+        // for low expected values use the Knuth method
         if self.lambda < 12.0 {
-            // for lambda below the threshold, use the Knuth method
             let mut result = 0;
             let mut p = 1.0;
             while p > self.exp_lambda {
@@ -68,23 +69,38 @@ impl IndependentSample<u64> for Poisson {
             }
             result - 1
         }
+        // high expected values - rejection method
         else {
-            // rejection method
+            // some cached values
             let tmp = (2.0*self.lambda).sqrt();
             let mut int_result: u64;
+
             loop {
                 let mut result;
                 let mut comp_dev;
-                // first, generate an easier deviate greater than 0
+
+                // we use the lorentzian distribution as the comparison distribution
+                // f(x) ~ 1/(1+x/^2)
                 loop {
-                    comp_dev = (PI*rng.gen::<f64>()).tan(); // comparison deviate
+                    // draw from the lorentzian distribution
+                    comp_dev = (PI*rng.gen::<f64>()).tan();
+                    // shift the peak of the comparison ditribution
                     result = tmp*comp_dev + self.lambda;
+                    // repeat the drawing until we are in the range of possible values
                     if result >= 0.0 { break; }
                 }
-                // now result is a random variable greater than 0 with Lorentzian distribution
+                // now the result is a random variable greater than 0 with Lorentzian distribution
+                // the result should be an integer value
                 result = result.floor();
                 int_result = result as u64;
+
+                // this is the ratio of the Poisson distribution to the comparison distribution
+                // the magic value scales the distribution function to a range of approximately 0-1
+                // since it is not exact, we multiply the ratio by 0.9 to avoid ratios greater than 1
+                // this doesn't change the resulting distribution, only increases the rate of failed drawings
                 let check = 0.9 * (1.0 + comp_dev*comp_dev) * (result*self.log_lambda - log_gamma(1.0 + result) - self.magic_val).exp();
+
+                // check with uniform random value - if below the threshold, we are within the target distribution
                 if rng.gen::<f64>() <= check { break; }
             }
             int_result
@@ -110,7 +126,7 @@ mod test {
         println!("Poisson average: {}", avg);
         assert!((avg - 10.0).abs() < 0.5); // not 100% certain, but probable enough
     }
-    
+
     #[test]
     #[should_panic]
     #[cfg_attr(target_env = "msvc", ignore)]