Merge pull request #366 from pitdicker/deny_doctest_warnings

Some more documentation work

Author: pitdicker

.travis.yml

@@ -34,6 +34,8 @@ matrix:
         - cargo test --features serde-1,log,nightly
         - cargo test --benches
         - cargo doc --no-deps --all --all-features
+        - cargo --list | egrep "^\s*deadlinks$" -q || cargo install cargo-deadlinks
+        - cargo deadlinks --dir target/doc
       after_success:
         - travis-cargo --only nightly doc-upload
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rand"
-version = "0.5.0-pre.0"
+version = "0.5.0-pre.0" # NB: When modifying, also modify html_root_url in lib.rs
 authors = ["The Rust Project Developers"]
 license = "MIT/Apache-2.0"
 readme = "README.md"
@@ -29,7 +29,7 @@ serde-1 = ["serde", "serde_derive"] # enables serialisation for PRNGs
 members = ["rand_core"]
 
 [dependencies]
-rand_core = { version = '0.1.0-pre.0', default-features = false }
+rand_core = { path="rand_core", default-features = false }
 log = { version = "0.4", optional = true }
 serde = { version = "1", optional = true }
 serde_derive = { version = "1", optional = true }
@@ -54,3 +54,7 @@ stdweb = { version = "0.4", optional = true }
 # This is for testing serde, unfortunately we can't specify feature-gated dev
 # deps yet, see: https://github.com/rust-lang/cargo/issues/1596
 bincode = "1.0"
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = [ "--all" ] # also document rand_core

benches/generators.rs

@@ -10,10 +10,10 @@ use std::mem::size_of;
 use test::{black_box, Bencher};
 
 use rand::{RngCore, Rng, SeedableRng, NewRng};
-use rand::{StdRng, SmallRng, OsRng, JitterRng, EntropyRng};
-use rand::{XorShiftRng, Hc128Rng, IsaacRng, Isaac64Rng, ChaChaRng};
-use rand::reseeding::ReseedingRng;
+use rand::{StdRng, SmallRng, OsRng, EntropyRng, ReseedingRng};
+use rand::prng::{XorShiftRng, Hc128Rng, IsaacRng, Isaac64Rng, ChaChaRng};
 use rand::prng::hc128::Hc128Core;
+use rand::jitter::JitterRng;
 use rand::thread_rng;
 
 macro_rules! gen_bytes {

rand_core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rand_core"
-version = "0.1.0-pre.0"
+version = "0.1.0-pre.0" # NB: When modifying, also modify html_root_url in lib.rs
 authors = ["The Rust Project Developers"]
 license = "MIT/Apache-2.0"
 readme = "README.md"

rand_core/src/lib.rs

@@ -83,8 +83,8 @@ pub mod le;
 /// output (except by communicating that the release has breaking changes).
 /// 
 /// Typically implementators will implement only one of the methods available
-/// in this trait directly, then use the helper functions from the [`impls`]
-/// module to implement the other methods.
+/// in this trait directly, then use the helper functions from the
+/// [`rand_core::impls`] module to implement the other methods.
 /// 
 /// It is recommended that implementations also implement:
 /// 
@@ -131,7 +131,7 @@ pub mod le;
 /// [rand]: https://crates.io/crates/rand
 /// [`Rng`]: ../rand/trait.Rng.html
 /// [`SeedableRng`]: trait.SeedableRng.html
-/// [`impls`]: impls/index.html
+/// [`rand_core::impls`]: ../rand_core/impls/index.html
 /// [`try_fill_bytes`]: trait.RngCore.html#tymethod.try_fill_bytes
 /// [`fill_bytes`]: trait.RngCore.html#tymethod.fill_bytes
 /// [`next_u32`]: trait.RngCore.html#tymethod.next_u32
@@ -143,23 +143,23 @@ pub trait RngCore {
     /// RNGs must implement at least one method from this trait directly. In
     /// the case this method is not implemented directly, it can be implemented
     /// using `self.next_u64() as u32` or
-    /// [via `fill_bytes`](impls/fn.next_u32_via_fill.html).
+    /// [via `fill_bytes`](../rand_core/impls/fn.next_u32_via_fill.html).
     fn next_u32(&mut self) -> u32;
 
     /// Return the next random `u64`.
     ///
     /// RNGs must implement at least one method from this trait directly. In
     /// the case this method is not implemented directly, it can be implemented
-    /// [via `next_u32`](impls/fn.next_u64_via_u32.html) or
-    /// [via `fill_bytes`](impls/fn.next_u64_via_fill.html).
+    /// [via `next_u32`](../rand_core/impls/fn.next_u64_via_u32.html) or
+    /// [via `fill_bytes`](../rand_core/impls/fn.next_u64_via_fill.html).
     fn next_u64(&mut self) -> u64;
 
     /// Fill `dest` with random data.
     ///
     /// RNGs must implement at least one method from this trait directly. In
     /// the case this method is not implemented directly, it can be implemented
-    /// [via `next_u32`](impls/fn.fill_bytes_via_u32.html) or
-    /// [via `next_u64`](impls/fn.fill_bytes_via_u64.html) or
+    /// [via `next_u32`](../rand_core/impls/fn.fill_bytes_via_u32.html) or
+    /// [via `next_u64`](../rand_core/impls/fn.fill_bytes_via_u64.html) or
     /// via `try_fill_bytes`; if this generator can fail the implementation
     /// must choose how best to handle errors here (e.g. panic with a
     /// descriptive message or log a warning and retry a few times).
@@ -329,7 +329,7 @@ pub trait SeedableRng: Sized {
     ///
     /// 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 [`XorShiftRng`] from another [`XorShiftRng`], which
+    /// wrong is seeding an Xorshift RNG from another Xorshift RNG, which
     /// will effectively clone the generator. In general seeding from a
     /// generator which is hard to predict is probably okay.
     ///
@@ -338,7 +338,6 @@ pub trait SeedableRng: Sized {
     /// 
     /// [`NewRng`]: ../rand/trait.NewRng.html
     /// [`OsRng`]: ../rand/os/struct.OsRng.html
-    /// [`XorShiftRng`]: ../rand/struct.XorShiftRng.html
     fn from_rng<R: RngCore>(mut rng: R) -> Result<Self, Error> {
         let mut seed = Self::Seed::default();
         rng.try_fill_bytes(seed.as_mut())?;

src/distributions/mod.rs

@@ -246,7 +246,7 @@ impl<'a, T, D: Distribution<T>> Distribution<T> for &'a D {
 /// use rand::distributions::Uniform;
 ///
 /// let mut rng = thread_rng();
-/// let mut erased_rng: &mut RngCore = &mut rng;
+/// let erased_rng: &mut RngCore = &mut rng;
 /// let val: f32 = erased_rng.sample(Uniform);
 /// println!("f32 from (0,1): {}", val);
 /// ```

src/distributions/range.rs

@@ -53,29 +53,29 @@ use distributions::float::IntoFloat;
 /// ```
 #[derive(Clone, Copy, Debug)]
 pub struct Range<X: SampleRange> {
-    inner: X::T,
+    inner: X::Impl,
 }
 
 impl<X: SampleRange> Range<X> {
     /// Create a new `Range` instance which samples uniformly from the half
     /// open range `[low, high)` (excluding `high`). Panics if `low >= high`.
     pub fn new(low: X, high: X) -> Range<X> {
         assert!(low < high, "Range::new called with `low >= high`");
-        Range { inner: X::T::new(low, high) }
+        Range { inner: X::Impl::new(low, high) }
     }
 
     /// Create a new `Range` instance which samples uniformly from the closed
     /// range `[low, high]` (inclusive). Panics if `low >= high`.
     pub fn new_inclusive(low: X, high: X) -> Range<X> {
         assert!(low < high, "Range::new called with `low >= high`");
-        Range { inner: X::T::new_inclusive(low, high) }
+        Range { inner: X::Impl::new_inclusive(low, high) }
     }
 
     /// Sample a single value uniformly from `[low, high)`.
     /// Panics if `low >= high`.
     pub fn sample_single<R: Rng + ?Sized>(low: X, high: X, rng: &mut R) -> X {
         assert!(low < high, "Range::sample_single called with low >= high");
-        X::T::sample_single(low, high, rng)
+        X::Impl::sample_single(low, high, rng)
     }
 }
 
@@ -88,7 +88,8 @@ impl<X: SampleRange> Distribution<X> for Range<X> {
 /// Helper trait for creating objects using the correct implementation of
 /// `RangeImpl` for the sampling type; this enables `Range::new(a, b)` to work.
 pub trait SampleRange: PartialOrd+Sized {
-    type T: RangeImpl<X = Self>;
+    /// The `RangeImpl` implementation supporting type `X`.
+    type Impl: RangeImpl<X = Self>;
 }
 
 /// Helper trait handling actual range sampling.
@@ -124,7 +125,7 @@ pub trait SampleRange: PartialOrd+Sized {
 /// }
 ///
 /// impl SampleRange for MyF32 {
-///     type T = RangeMyF32;
+///     type Impl = RangeMyF32;
 /// }
 ///
 /// let (low, high) = (MyF32(17.0f32), MyF32(22.0f32));
@@ -183,7 +184,7 @@ macro_rules! range_int_impl {
     ($ty:ty, $signed:ty, $unsigned:ident,
      $i_large:ident, $u_large:ident) => {
         impl SampleRange for $ty {
-            type T = RangeInt<$ty>;
+            type Impl = RangeInt<$ty>;
         }
 
         impl RangeImpl for RangeInt<$ty> {
@@ -428,7 +429,7 @@ pub struct RangeFloat<X> {
 macro_rules! range_float_impl {
     ($ty:ty, $bits_to_discard:expr, $next_u:ident) => {
         impl SampleRange for $ty {
-            type T = RangeFloat<$ty>;
+            type Impl = RangeFloat<$ty>;
         }
 
         impl RangeImpl for RangeFloat<$ty> {
@@ -566,7 +567,7 @@ mod tests {
             }
         }
         impl SampleRange for MyF32 {
-            type T = RangeMyF32;
+            type Impl = RangeMyF32;
         }
 
         let (low, high) = (MyF32{ x: 17.0f32 }, MyF32{ x: 22.0f32 });

src/entropy_rng.rs

@@ -11,7 +11,8 @@
 //! Entropy generator, or wrapper around external generators
 
 use rand_core::{RngCore, CryptoRng, Error, impls};
-use {OsRng, JitterRng};
+use os::OsRng;
+use jitter::JitterRng;
 
 /// A generator provided specifically for securely seeding algorithmic
 /// generators (PRNGs).