Documentation improvements

Author: pitdicker

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,8 +736,8 @@ 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 `u8` arrays (expressed with the
+    /// `Sized + AsMut<[u8]>` bound).
     ///
     /// 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
@@ -764,19 +764,19 @@ 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`.
+    /// Also cryptographically secure PRNG's (like `thread_rng`) can be used
+    /// without hesitation.
     ///
     /// Seeding a small PRNG from another small PRNG is be possible, but
     /// something to be careful with. An extreme example of how this can go
@@ -786,6 +786,8 @@ pub trait SeedableRng: Sized {
     /// 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
     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 +796,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 PRNG's, 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 +813,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.