SmallRng: Improve documentation

Now initializing using `NewRng` is used to simplify the examples. The
documentation for `SmallRng` recommends using `thread_rng` when
initializing a lot of generators.

Author: vks

src/distributions/exponential.rs

@@ -30,11 +30,10 @@ use distributions::{ziggurat, ziggurat_tables, Distribution};
 ///
 /// # Example
 /// ```rust
-/// use rand::{SeedableRng, SmallRng, Rng, thread_rng};
+/// use rand::{NewRng, SmallRng, Rng};
 /// use rand::distributions::Exp1;
 ///
-/// let val: f64 = SmallRng::from_rng(&mut thread_rng())
-///     .unwrap().sample(Exp1);
+/// let val: f64 = SmallRng::new().unwrap().sample(Exp1);
 /// println!("{}", val);
 /// ```
 #[derive(Clone, Copy, Debug)]

src/distributions/float.rs

@@ -49,11 +49,10 @@ macro_rules! float_impls {
             ///
             /// # Example
             /// ```rust
-            /// use rand::{SeedableRng, SmallRng, Rng, thread_rng};
+            /// use rand::{NewRng, SmallRng, Rng};
             /// use rand::distributions::Uniform;
             ///
-            /// let val: f32 = SmallRng::from_rng(&mut thread_rng())
-            ///     .unwrap().sample(Uniform);
+            /// let val: f32 = SmallRng::new().unwrap().sample(Uniform);
             /// println!("f32 from (0,1): {}", val);
             /// ```
             fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> $ty {

src/distributions/mod.rs

@@ -163,11 +163,10 @@ impl<'a, T, D: Distribution<T>> Distribution<T> for &'a D {
 ///
 /// # Example
 /// ```rust
-/// use rand::{SeedableRng, SmallRng, Rng, thread_rng};
+/// use rand::{NewRng, SmallRng, Rng};
 /// use rand::distributions::Uniform;
 ///
-/// let val: f32 = SmallRng::from_rng(&mut thread_rng())
-///     .unwrap().sample(Uniform);
+/// let val: f32 = SmallRng::new().unwrap().sample(Uniform);
 /// println!("f32 from [0,1): {}", val);
 /// ```
 ///

src/distributions/normal.rs

@@ -28,11 +28,10 @@ use distributions::{ziggurat, ziggurat_tables, Distribution, Uniform};
 ///
 /// # Example
 /// ```rust
-/// use rand::{SeedableRng, SmallRng, Rng, thread_rng};
+/// use rand::{NewRng, SmallRng, Rng};
 /// use rand::distributions::StandardNormal;
 ///
-/// let val: f64 = SmallRng::from_rng(&mut thread_rng())
-///     .unwrap().sample(StandardNormal);
+/// let val: f64 = SmallRng::new().unwrap().sample(StandardNormal);
 /// println!("{}", val);
 /// ```
 #[derive(Clone, Copy, Debug)]

src/lib.rs

@@ -1088,8 +1088,8 @@ impl SeedableRng for StdRng {
 
 /// An RNG recommended when small state, cheap initialization and good
 /// performance are required. The PRNG algorithm in `SmallRng` is choosen to be
-/// efficient on the current platform, without consideration for cryptography or
-/// security. The size of its state is much smaller than for `StdRng`.
+/// efficient on the current platform, **without consideration for cryptography
+/// or security**. The size of its state is much smaller than for `StdRng`.
 ///
 /// Reproducibility of output from this generator is however not required, thus
 /// future library versions may use a different internal generator with
@@ -1099,10 +1099,30 @@ impl SeedableRng for StdRng {
 ///
 /// The current algorithm used on all platforms is [Xorshift].
 ///
+/// # Examples
+///
+/// Initializing `StdRng` with a random seed can be done using `NewRng`:
+///
+/// ```
+/// use rand::{NewRng, SmallRng};
+///
+/// // Create small, cheap to initialize and fast RNG with a random seed.
+/// // The randomness is supplied by the operating system.
+/// let mut small_rng = SmallRng::new().unwrap();
+/// ```
+///
+/// When initializing a lot of `SmallRng`, using `thread_rng` can be more
+/// efficient:
+///
 /// ```
 /// use rand::{SeedableRng, SmallRng, thread_rng};
 ///
-/// let _rng = SmallRng::from_rng(&mut thread_rng()).unwrap();
+/// // Create a big, expensive to initialize and slower, but unpredictable RNG.
+/// // This is cached and done only once per thread.
+/// let mut thread_rng = thread_rng();
+/// // Create small, cheap to initialize and fast RNG with a random seed.
+/// // This is very unlikely to fail.
+/// let mut small_rng = SmallRng::from_rng(&mut thread_rng).unwrap();
 /// ```
 ///
 /// [Xorshift]: struct.XorShiftRng.html