Uniform range sampling: improve docs

Final part of #395

Author: dhardy

src/distributions/uniform.rs

@@ -162,9 +162,9 @@ pub trait UniformImpl: Sized {
     /// this.
     ///
     /// Via this method, implementations can provide a method optimized for
-    /// sampling only a limited number of values from the range. The default
-    /// implementation just sets up a `Uniform` with `UniformImpl::new` and samples
-    /// from that.
+    /// sampling only a single value from the specified range. The default
+    /// implementation simply calls `UniformImpl::new` then `sample` on the
+    /// result.
     fn sample_single<R: Rng + ?Sized>(low: Self::X, high: Self::X, rng: &mut R)
         -> Self::X
     {

src/lib.rs

@@ -325,10 +325,11 @@ pub trait Rng: RngCore {
     /// `low` and exclusive of `high`.
     ///
     /// This is a convenience wrapper around
-    /// `distributions::Uniform`. If this function will be called
-    /// repeatedly with the same arguments, one should use `Uniform`, as
-    /// that will amortize the computations that allow for perfect
-    /// uniformity, as they only happen when constructing the `Uniform`.
+    /// `distributions::Uniform::sample_single`. If this function will be called
+    /// repeatedly with the same arguments, it will likely be faster to
+    /// construct a `Uniform` distribution object and sample from that; this
+    /// allows amortization of the computations that allow for perfect
+    /// uniformity within the `Uniform::new` constructor.
     ///
     /// # Panics
     ///