Small doc tweaks

Author: pitdicker

src/lib.rs

@@ -260,11 +260,12 @@ pub mod isaac {
 #[cfg(feature="std")] mod thread_rng;
 
 
-/// A type that can be randomly generated using an `Rng`.
+/// A type that can be randomly generated using an [`Rng`].
 /// 
 /// This is merely an adaptor around the [`Uniform`] distribution for
 /// convenience and backwards-compatibility.
 /// 
+/// [`Rng`]: trait.Rng.html
 /// [`Uniform`]: distributions/struct.Uniform.html
 #[deprecated(since="0.5.0", note="replaced by distributions::Uniform")]
 pub trait Rand : Sized {
@@ -734,7 +735,7 @@ impl<R: RngCore> Iterator for AsciiGenerator<R> {
 
 
 /// A convenient way to seed new algorithmic generators with fresh entropy from
-/// `EntropyRng`.
+/// [`EntropyRng`].
 ///
 /// This is the recommended way to create PRNGs, unless a deterministic seed is
 /// desired (in which case [`SeedableRng::from_seed`] should be used).
@@ -751,6 +752,7 @@ impl<R: RngCore> Iterator for AsciiGenerator<R> {
 /// println!("Random die roll: {}", rng.gen_range(1, 7));
 /// ```
 ///
+/// [`EntropyRng`]: struct.EntropyRng.html
 /// [`SeedableRng`]: https://docs.rs/rand_core/0.1/rand_core/trait.SeedableRng.html
 /// [`SeedableRng::from_seed`]: https://docs.rs/rand_core/0.1/rand_core/trait.SeedableRng.html#tymethod.from_seed
 #[cfg(feature="std")]
@@ -802,9 +804,10 @@ impl<R: SeedableRng> NewRng for R {
 /// future library versions may use a different internal generator with
 /// different output. Further, this generator may not be portable and can
 /// produce different output depending on the architecture. If you require
-/// reproducible output, use a named RNG, for example `ChaChaRng`.
+/// reproducible output, use a named RNG, for example [`ChaChaRng`].
 ///
 /// [HC-128]: prng/hc128/struct.Hc128Rng.html
+/// [`ChaChaRng`]: prng/chacha/struct.ChaChaRng.html
 #[derive(Clone, Debug)]
 pub struct StdRng(Hc128Rng);
 
@@ -845,19 +848,19 @@ impl CryptoRng for StdRng {}
 /// 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`.
+/// 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
 /// different output. Further, this generator may not be portable and can
 /// produce different output depending on the architecture. If you require
-/// reproducible output, use a named RNG, for example `XorShiftRng`.
+/// reproducible output, use a named RNG, for example [`XorShiftRng`].
 ///
 /// The current algorithm used on all platforms is [Xorshift].
 ///
 /// # Examples
 ///
-/// Initializing `StdRng` with a random seed can be done using `NewRng`:
+/// Initializing `SmallRng` with a random seed can be done using [`NewRng`]:
 ///
 /// ```
 /// # use rand::Rng;
@@ -869,7 +872,7 @@ impl CryptoRng for StdRng {}
 /// # let v: u32 = small_rng.gen();
 /// ```
 ///
-/// When initializing a lot of `SmallRng`, using `thread_rng` can be more
+/// When initializing a lot of `SmallRng`'s, using [`thread_rng`] can be more
 /// efficient:
 ///
 /// ```
@@ -887,7 +890,11 @@ impl CryptoRng for StdRng {}
 ///     .collect();
 /// ```
 ///
-/// [Xorshift]: struct.XorShiftRng.html
+/// [`NewRng`]: trait.NewRng.html
+/// [`StdRng`]: struct.StdRng.html
+/// [`thread_rng`]: fn.thread_rng.html
+/// [Xorshift]: prng/struct.XorShiftRng.html
+/// [`XorShiftRng`]: prng/struct.XorShiftRng.html
 #[derive(Clone, Debug)]
 pub struct SmallRng(XorShiftRng);
 
@@ -923,7 +930,7 @@ impl SeedableRng for SmallRng {
     }
 }
 
-/// DEPRECATED: use `SmallRng` instead.
+/// DEPRECATED: use [`SmallRng`] instead.
 ///
 /// Create a weak random number generator with a default algorithm and seed.
 ///
@@ -933,6 +940,8 @@ impl SeedableRng for SmallRng {
 /// create the `Rng` yourself.
 ///
 /// This will seed the generator with randomness from `thread_rng`.
+///
+/// [`SmallRng`]: struct.SmallRng.html
 #[deprecated(since="0.5.0", note="removed in favor of SmallRng")]
 #[cfg(feature="std")]
 pub fn weak_rng() -> XorShiftRng {

src/os.rs

@@ -15,7 +15,9 @@ use std::fmt;
 use rand_core::{RngCore, Error, impls};
 
 /// A random number generator that retrieves randomness straight from the
-/// operating system. This is the preferred external source of entropy for most
+/// operating system.
+///
+/// This is the preferred external source of entropy for most
 /// applications. Commonly it is used to initialize a user-space RNG, which can
 /// then be used to generate random values with much less overhead than `OsRng`.
 ///

src/thread_rng.rs

@@ -45,8 +45,10 @@ use reseeding::ReseedingRng;
 const THREAD_RNG_RESEED_THRESHOLD: u64 = 32*1024*1024; // 32 MiB
 
 /// The type returned by [`thread_rng`], essentially just a reference to the
-/// PRNG in thread-local memory. Cloning this handle just produces a new
-/// reference to the same thread-local generator.
+/// PRNG in thread-local memory.
+///
+/// Cloning this handle just produces a new reference to the same thread-local
+/// generator.
 /// 
 /// [`thread_rng`]: fn.thread_rng.html
 #[derive(Clone, Debug)]