From 34239fa520fa2c03052118d22cfef84655dbc65d Mon Sep 17 00:00:00 2001
From: Paul Dicker <pitdicker@gmail.com>
Date: Sat, 20 Jan 2018 16:30:13 +0100
Subject: [PATCH] Documentation improvements

---
 src/lib.rs | 55 ++++++++++++++++++++++++++++++------------------------
 1 file changed, 31 insertions(+), 24 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 27214ae5f24..2af8c34f5f1 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -276,7 +276,7 @@ use prng::Isaac64Rng as IsaacWordRng;
 
 use distributions::{Range, IndependentSample};
 use distributions::range::SampleRange;
-#[cfg(feature="std")]use reseeding::{ReseedingRng, ReseedWithNew};
+#[cfg(feature="std")] use reseeding::{ReseedingRng, ReseedWithNew};
 
 // public modules
 pub mod distributions;
@@ -736,12 +736,12 @@ impl<'a, R: Rng> Iterator for AsciiGenerator<'a, R> {
 ///
 /// Each pseudo-random number generator (PRNG) should implement this.
 pub trait SeedableRng: Sized {
-    /// Seed type, which is restricted to `u8` arrays with a length of
-    /// 4, 8, 12, 16, 24 and 32.
+    /// Seed type, which is restricted to types mutably-dereferencable as `u8`
+    /// arrays (we recommend `[u8; N]` for some `N`).
     ///
-    /// It is recommended to seed PRNG's with a seed of more than circa
-    /// 100 bits, which means an array of `[u8; 12]` or greater to avoid picking
-    /// RNG's with partially overlapping periods.
+    /// It is recommended to seed PRNGs with a seed of at least circa 100 bits,
+    /// which means an array of `[u8; 12]` or greater to avoid picking RNGs with
+    /// partially overlapping periods.
     ///
     /// For cryptographic RNG's a seed of 256 bits is recommended, `[u8; 32]`.
     type Seed: Sized + Default + AsMut<[u8]>;
@@ -764,28 +764,32 @@ pub trait SeedableRng: Sized {
 
     /// Create a new PRNG seeded from another `Rng`.
     ///
-    /// This is the recommended way to initialize PRNGs. See the `NewRng`
-    /// trait that provides a convenient `new` method using `from_rng` and a
-    /// good entropy source.
+    /// This is the recommended way to initialize PRNGs. The [`NewRng`] trait
+    /// provides a convenient new method based on `from_rng`.
     ///
-    /// It is recommended to use a good source of randomness to initialize the
-    /// PRNG. Otherwise small PRNG's could show statistical bias in the first
-    /// couple of results, and possibly not use their entire period well.
-    /// Cryptographic PRNG's can be less secure or even insecure when they are
-    /// seeded from a non-cryptographic PRNG.
+    /// It is important to use a good source of randomness to initialize the
+    /// PRNG. Cryptographic PRNG may be rendered insecure when seeded from a
+    /// non-cryptographic PRNG or with insufficient entropy.
+    /// Many non-cryptographic PRNGs will show statistical bias in their first
+    /// results if their seed numbers are small or if there is a simple pattern
+    /// between them.
     ///
-    /// Examples of good RNG's for seeding are entropy sources like `OsRng` and
-    /// `JitterRng`. Also cryptographically secure PRNG's (like `thread_rng`)
-    /// can be used without hesitation.
+    /// Prefer to seed from a strong external entropy source like [`OsRng`] or
+    /// from a cryptographic PRNG; if creating a new generator for cryptography
+    /// you *must* do this.
     ///
-    /// Seeding a small PRNG from another small PRNG is be possible, but
+    /// Seeding a small PRNG from another small PRNG is possible, but
     /// something to be careful with. An extreme example of how this can go
     /// wrong is seeding an Xorshift RNG from another Xorshift RNG. That will
-    /// effectively clone the generator.
+    /// effectively clone the generator. In general seeding from a generator
+    /// which is hard to predict is probably okay.
     ///
     /// PRNG implementations are allowed to assume that a good RNG is provided
     /// for seeding, and that it is cryptographically secure when appropriate.
     /// There are no reproducibility requirements like endianness conversion.
+    ///
+    /// [`NewRng`]: trait.NewRng.html
+    /// [`OsRng`]: os/struct.OsRng.html
     fn from_rng<R: Rng>(mut rng: R) -> Result<Self, Error> {
         let mut seed = Self::Seed::default();
         rng.try_fill_bytes(seed.as_mut())?;
@@ -794,13 +798,14 @@ pub trait SeedableRng: Sized {
 }
 
 
-/// Seeding mechanism for PRNGs, providing a `new` function.
-/// This is the recommended way to create (pseudo) random number generators,
-/// unless a deterministic seed is desired (in which case
-/// `SeedableRng::from_seed` should be used).
+/// A convenient way to seed new algorithmic generators, otherwise known as
+/// pseudo-random number generators (PRNGs).
+///
+/// This is the recommended way to create PRNGs, unless a deterministic seed is
+/// desired (in which case `SeedableRng::from_seed` should be used).
 ///
 /// Note: this trait is automatically implemented for any PRNG implementing
-/// `SeedableRng` and is not intended to be implemented by users.
+/// [`SeedableRng`] and is not intended to be implemented by users.
 ///
 /// ## Example
 ///
@@ -810,6 +815,8 @@ pub trait SeedableRng: Sized {
 /// let mut rng = StdRng::new().unwrap();
 /// println!("Random die roll: {}", rng.gen_range(1, 7));
 /// ```
+///
+/// [`SeedableRng`]: trait.SeedableRng.html
 #[cfg(feature="std")]
 pub trait NewRng: SeedableRng {
     /// Creates a new instance, automatically seeded with fresh entropy.