Small doc polishing

Author: pitdicker

src/lib.rs

@@ -278,7 +278,7 @@ use distributions::uniform::SampleUniform;
 
 /// An automatically-implemented extension trait on [`RngCore`] providing high-level
 /// generic methods for sampling values and other convenience methods.
-/// 
+///
 /// This is the primary trait to use when generating random values.
 /// 
 /// # Generic usage
@@ -322,7 +322,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// use rand::{thread_rng, Rng};
     ///
     /// let mut rng = thread_rng();
@@ -351,7 +351,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// use rand::{thread_rng, Rng};
     ///
     /// let mut rng = thread_rng();
@@ -368,7 +368,7 @@ pub trait Rng: RngCore {
     ///
     /// ### Example
     ///
-    /// ```rust
+    /// ```
     /// use rand::{thread_rng, Rng};
     /// use rand::distributions::Uniform;
     ///
@@ -383,7 +383,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// use rand::{thread_rng, Rng};
     /// use rand::distributions::{Alphanumeric, Uniform, Standard};
     ///
@@ -425,7 +425,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// use rand::{thread_rng, Rng};
     ///
     /// let mut arr = [0i8; 20];
@@ -454,7 +454,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// # use rand::Error;
     /// use rand::{thread_rng, Rng};
     ///
@@ -481,7 +481,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// use rand::{thread_rng, Rng};
     ///
     /// let mut rng = thread_rng();
@@ -546,7 +546,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// use rand::{thread_rng, Rng};
     ///
     /// let mut rng = thread_rng();
@@ -591,7 +591,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// # #![allow(deprecated)]
     /// use rand::{thread_rng, Rng};
     ///
@@ -614,7 +614,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// # #![allow(deprecated)]
     /// use rand::{thread_rng, Rng};
     ///
@@ -642,7 +642,7 @@ impl<R: RngCore + ?Sized> Rng for R {}
 /// PRNGs, though two alternatives may be considered:
 ///
 /// *   Deterministic creation using [`SeedableRng::from_seed`] with a fixed seed
-/// *   Seeding from `thread_rng`: `SeedableRng::from_rng(thread_rng())?`;
+/// *   Seeding from [`thread_rng`]: `SeedableRng::from_rng(thread_rng())?`;
 ///     this will usually be faster and should also be secure, but requires
 ///     trusting one extra component.
 ///
@@ -655,9 +655,10 @@ impl<R: RngCore + ?Sized> Rng for R {}
 /// println!("Random die roll: {}", rng.gen_range(1, 7));
 /// ```
 ///
-/// [`EntropyRng`]: struct.EntropyRng.html
+/// [`EntropyRng`]: rngs/struct.EntropyRng.html
 /// [`SeedableRng`]: trait.SeedableRng.html
 /// [`SeedableRng::from_seed`]: trait.SeedableRng.html#tymethod.from_seed
+/// [`thread_rng`]: fn.thread_rng.html
 #[cfg(feature="std")]
 pub trait FromEntropy: SeedableRng {
     /// Creates a new instance, automatically seeded with fresh entropy.
@@ -672,7 +673,7 @@ pub trait FromEntropy: SeedableRng {
     /// If all entropy sources fail this will panic. If you need to handle
     /// errors, use the following code, equivalent aside from error handling:
     ///
-    /// ```rust
+    /// ```
     /// # use rand::Error;
     /// use rand::{Rng, StdRng, EntropyRng, SeedableRng};
     ///
@@ -703,6 +704,9 @@ impl<R: SeedableRng> FromEntropy for R {
 /// documentation of the entropy source and [`Standard`] for documentation of
 /// distributions and type-specific generation.
 ///
+/// Use [`thread_rng`] directly when you need more features, for example
+/// `thread_rng().gen_range(a, b)` to generate values uniformly in some range.
+///
 /// # Examples
 ///
 /// ```

src/rngs/entropy.rs

@@ -30,9 +30,9 @@ use {OsRng, JitterRng};
 /// external entropy then primarily use the local PRNG ([`thread_rng`] is
 /// provided as a convenient, local, automatically-seeded CSPRNG).
 ///
-/// [`OsRng`]: os/struct.OsRng.html
-/// [`JitterRng`]: jitter/struct.JitterRng.html
-/// [`thread_rng`]: fn.thread_rng.html
+/// [`OsRng`]: struct.OsRng.html
+/// [`JitterRng`]: struct.JitterRng.html
+/// [`thread_rng`]: ../fn.thread_rng.html
 #[derive(Debug)]
 pub struct EntropyRng {
     rng: EntropySource,

src/rngs/read.rs

@@ -23,18 +23,21 @@ use rand_core::{RngCore, Error, ErrorKind, impls};
 ///
 /// `ReadRng` uses `std::io::read_exact`, which retries on interrupts. All other
 /// errors from the underlying reader, including when it does not have enough
-/// data, will only be reported through `try_fill_bytes`. The other `RngCore`
-/// methods will panic in case of an error error.
+/// data, will only be reported through [`try_fill_bytes`]. The other
+/// [`RngCore`] methods will panic in case of an error.
 ///
 /// # Example
 ///
-/// ```rust
+/// ```
 /// use rand::{read, Rng};
 ///
 /// let data = vec![1, 2, 3, 4, 5, 6, 7, 8];
 /// let mut rng = read::ReadRng::new(&data[..]);
 /// println!("{:x}", rng.gen::<u32>());
 /// ```
+///
+/// [`RngCore`]: ../trait.RngCore.html
+/// [`try_fill_bytes`]: ../trait.RngCore.html#tymethod.try_fill_bytes
 #[derive(Debug)]
 pub struct ReadRng<R> {
     reader: R

src/rngs/small.rs

@@ -14,9 +14,11 @@ use {RngCore, SeedableRng, Error};
 use prng::XorShiftRng;
 
 /// An RNG recommended when small state, cheap initialization and good
-/// performance are required. The PRNG algorithm in `SmallRng` is chosen to be
-/// efficient on the current platform, **without consideration for cryptography
-/// or security**. The size of its state is much smaller than for [`StdRng`].
+/// performance are required.
+///
+/// The PRNG algorithm in `SmallRng` is chosen to be 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