From b4513063af77e66f64f374d3aecbf5af3239fb77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D1=80=D1=82=D1=91=D0=BC=20=D0=9F=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2=20=5BArtyom=20Pavlov=5D?= Date: Fri, 11 Jan 2019 03:03:32 +0300 Subject: [PATCH 1/3] Use RFC 1946 for doc links --- rand_chacha/src/chacha.rs | 6 +-- rand_core/src/block.rs | 35 +++++------- rand_core/src/lib.rs | 73 +++++++++++-------------- rand_hc/src/hc128.rs | 3 -- rand_isaac/src/isaac.rs | 14 ++--- rand_isaac/src/isaac64.rs | 15 +++--- rand_os/src/lib.rs | 9 ++-- rand_xoshiro/src/lib.rs | 11 ---- src/distributions/exponential.rs | 2 +- src/distributions/float.rs | 12 ++--- src/distributions/mod.rs | 91 ++++++++++++++------------------ src/distributions/normal.rs | 2 +- src/distributions/uniform.rs | 51 +++++++----------- src/distributions/weighted.rs | 14 +++-- src/lib.rs | 53 ++++++------------- src/rngs/adapter/read.rs | 15 +++--- src/rngs/adapter/reseeding.rs | 10 ++-- src/rngs/entropy.rs | 9 ++-- src/rngs/jitter.rs | 23 ++++---- src/rngs/mod.rs | 42 +++++---------- src/rngs/small.rs | 14 +++-- src/rngs/std.rs | 4 +- src/rngs/thread.rs | 10 ++-- src/seq/index.rs | 2 +- src/seq/mod.rs | 19 +++---- 25 files changed, 206 insertions(+), 333 deletions(-) diff --git a/rand_chacha/src/chacha.rs b/rand_chacha/src/chacha.rs index 86f191e49ab..b8215ac3b81 100644 --- a/rand_chacha/src/chacha.rs +++ b/rand_chacha/src/chacha.rs @@ -62,10 +62,8 @@ const STATE_WORDS: usize = 16; /// [^2]: [eSTREAM: the ECRYPT Stream Cipher Project]( /// http://www.ecrypt.eu.org/stream/) /// -/// [`set_word_pos`]: #method.set_word_pos -/// [`set_stream`]: #method.set_stream -/// [`BlockRng`]: ../rand_core/block/struct.BlockRng.html -/// [`RngCore`]: ../rand_core/trait.RngCore.html +/// [`set_word_pos`]: ChaChaRng::set_word_pos +/// [`set_stream`]: ChaChaRng::set_stream #[derive(Clone, Debug)] pub struct ChaChaRng(BlockRng); diff --git a/rand_core/src/block.rs b/rand_core/src/block.rs index de480e45401..c02bab29880 100644 --- a/rand_core/src/block.rs +++ b/rand_core/src/block.rs @@ -16,7 +16,8 @@ //! implementations only need to concern themselves with generation of the //! block, not the various [`RngCore`] methods (especially [`fill_bytes`], where //! the optimal implementations are not trivial), and this allows -//! [`ReseedingRng`] perform periodic reseeding with very low overhead. +//! `ReseedingRng` (see [`rand`](https://docs.rs/rand) crate) perform periodic +//! reseeding with very low overhead. //! //! # Example //! @@ -46,10 +47,8 @@ //! type MyRng = BlockRng; //! ``` //! -//! [`BlockRngCore`]: trait.BlockRngCore.html -//! [`RngCore`]: ../trait.RngCore.html -//! [`fill_bytes`]: ../trait.RngCore.html#tymethod.fill_bytes -//! [`ReseedingRng`]: ../../rand/rngs/adapter/struct.ReseedingRng.html +//! [`BlockRngCore`]: crate::block::BlockRngCore +//! [`fill_bytes`]: RngCore::fill_bytes use core::convert::AsRef; use core::fmt; @@ -60,7 +59,7 @@ use impls::{fill_via_u32_chunks, fill_via_u64_chunks}; /// blocks (typically `[u32; N]`). This technique is commonly used by /// cryptographic RNGs to improve performance. /// -/// See the [module documentation](index.html) for details. +/// See the [module][crate::block] documentation for details. pub trait BlockRngCore { /// Results element type, e.g. `u32`. type Item; @@ -105,15 +104,10 @@ pub trait BlockRngCore { /// /// For easy initialization `BlockRng` also implements [`SeedableRng`]. /// -/// [`BlockRngCore`]: BlockRngCore.t.html -/// [`BlockRngCore::generate`]: trait.BlockRngCore.html#tymethod.generate -/// [`BlockRng64`]: struct.BlockRng64.html -/// [`RngCore`]: ../RngCore.t.html -/// [`next_u32`]: ../trait.RngCore.html#tymethod.next_u32 -/// [`next_u64`]: ../trait.RngCore.html#tymethod.next_u64 -/// [`fill_bytes`]: ../trait.RngCore.html#tymethod.fill_bytes -/// [`try_fill_bytes`]: ../trait.RngCore.html#tymethod.try_fill_bytes -/// [`SeedableRng`]: ../SeedableRng.t.html +/// [`next_u32`]: RngCore::next_u32 +/// [`next_u64`]: RngCore::next_u64 +/// [`fill_bytes`]: RngCore::fill_bytes +/// [`try_fill_bytes`]: RngCore::try_fill_bytes #[derive(Clone)] #[cfg_attr(feature="serde1", derive(Serialize, Deserialize))] pub struct BlockRng { @@ -314,13 +308,10 @@ impl SeedableRng for BlockRng { /// values. If the requested length is not a multiple of 8, some bytes will be /// discarded. /// -/// [`BlockRngCore`]: BlockRngCore.t.html -/// [`RngCore`]: ../RngCore.t.html -/// [`next_u32`]: ../trait.RngCore.html#tymethod.next_u32 -/// [`next_u64`]: ../trait.RngCore.html#tymethod.next_u64 -/// [`fill_bytes`]: ../trait.RngCore.html#tymethod.fill_bytes -/// [`try_fill_bytes`]: ../trait.RngCore.html#tymethod.try_fill_bytes -/// [`BlockRng`]: struct.BlockRng.html +/// [`next_u32`]: RngCore::next_u32 +/// [`next_u64`]: RngCore::next_u64 +/// [`fill_bytes`]: RngCore::fill_bytes +/// [`try_fill_bytes`]: RngCore::try_fill_bytes #[derive(Clone)] #[cfg_attr(feature="serde1", derive(Serialize, Deserialize))] pub struct BlockRng64 { diff --git a/rand_core/src/lib.rs b/rand_core/src/lib.rs index a65db932f02..4239c624429 100644 --- a/rand_core/src/lib.rs +++ b/rand_core/src/lib.rs @@ -10,7 +10,7 @@ //! Random number generation traits //! //! This crate is mainly of interest to crates publishing implementations of -//! [`RngCore`]. Other users are encouraged to use the [rand] crate instead +//! [`RngCore`]. Other users are encouraged to use the [`rand`] crate instead //! which re-exports the main traits and error types. //! //! [`RngCore`] is the core trait implemented by algorithmic pseudo-random number @@ -25,12 +25,7 @@ //! The [`impls`] and [`le`] sub-modules include a few small functions to assist //! implementation of [`RngCore`]. //! -//! [rand]: https://crates.io/crates/rand -//! [`RngCore`]: trait.RngCore.html -//! [`SeedableRng`]: trait.SeedableRng.html -//! [`Error`]: struct.Error.html -//! [`impls`]: impls/index.html -//! [`le`]: le/index.html +//! [`rand`]: https://docs.rs/rand #![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png", html_favicon_url = "https://www.rust-lang.org/favicon.ico", @@ -68,8 +63,8 @@ pub mod le; /// /// This trait encapsulates the low-level functionality common to all /// generators, and is the "back end", to be implemented by generators. -/// End users should normally use [`Rng`] from the [rand] crate, which is -/// automatically implemented for every type implementing `RngCore`. +/// End users should normally use `Rng` trait from the [`rand`] crate, +/// which is automatically implemented for every type implementing `RngCore`. /// /// Three different methods for generating random data are provided since the /// optimal implementation of each is dependent on the type of generator. There @@ -89,7 +84,7 @@ pub mod le; /// /// Typically implementators will implement only one of the methods available /// in this trait directly, then use the helper functions from the -/// [`rand_core::impls`] module to implement the other methods. +/// [`impls`] module to implement the other methods. /// /// It is recommended that implementations also implement: /// @@ -135,40 +130,37 @@ pub mod le; /// } /// ``` /// -/// [rand]: https://crates.io/crates/rand -/// [`Rng`]: ../rand/trait.Rng.html -/// [`SeedableRng`]: trait.SeedableRng.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 -/// [`next_u64`]: trait.RngCore.html#tymethod.next_u64 -/// [`CryptoRng`]: trait.CryptoRng.html +/// [`rand`]: https://docs.rs/rand +/// [`try_fill_bytes`]: RngCore::try_fill_bytes +/// [`fill_bytes`]: RngCore::fill_bytes +/// [`next_u32`]: RngCore::next_u32 +/// [`next_u64`]: RngCore::next_u64 pub trait RngCore { /// Return the next random `u32`. /// /// 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`](../rand_core/impls/fn.next_u32_via_fill.html). + /// using `self.next_u64() as u32` or via + /// [`fill_bytes`][impls::next_u32_via_fill]. 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`](../rand_core/impls/fn.next_u64_via_u32.html) or - /// [via `fill_bytes`](../rand_core/impls/fn.next_u64_via_fill.html). + /// via [`next_u32`][impls::next_u64_via_u32] or via + /// [`fill_bytes`][impls::next_u64_via_fill]. 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_u*`](../rand_core/impls/fn.fill_bytes_via_next.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). + /// via [`next_u*`][impls::fill_bytes_via_next] or + /// via [`try_fill_bytes`][RngCore::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). /// /// This method should guarantee that `dest` is entirely filled /// with new data, and may panic if this is impossible @@ -188,7 +180,7 @@ pub trait RngCore { /// `fill_bytes` may be implemented with /// `self.try_fill_bytes(dest).unwrap()` or more specific error handling. /// - /// [`fill_bytes`]: trait.RngCore.html#method.fill_bytes + /// [`fill_bytes`]: RngCore::fill_bytes fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>; } @@ -213,8 +205,7 @@ pub trait RngCore { /// Note also that use of a `CryptoRng` does not protect against other /// weaknesses such as seeding from a weak entropy source or leaking state. /// -/// [`RngCore`]: trait.RngCore.html -/// [`BlockRngCore`]: ../rand_core/block/trait.BlockRngCore.html +/// [`BlockRngCore`]: block::BlockRngCore pub trait CryptoRng {} /// A random number generator that can be explicitly seeded. @@ -222,11 +213,11 @@ pub trait CryptoRng {} /// This trait encapsulates the low-level functionality common to all /// pseudo-random number generators (PRNGs, or algorithmic generators). /// -/// The [`rand::FromEntropy`] trait is automatically implemented for every type -/// implementing `SeedableRng`, providing a convenient `from_entropy()` -/// constructor. +/// The `FromEntropy` trait from [`rand`] crate is automatically +/// implemented for every type implementing `SeedableRng`, providing +/// a convenient `from_entropy()` constructor. /// -/// [`rand::FromEntropy`]: ../rand/trait.FromEntropy.html +/// [`rand`]: https://docs.rs/rand pub trait SeedableRng: Sized { /// Seed type, which is restricted to types mutably-dereferencable as `u8` /// arrays (we recommend `[u8; N]` for some `N`). @@ -340,8 +331,8 @@ pub trait SeedableRng: Sized { /// Create a new PRNG seeded from another `Rng`. /// /// This is the recommended way to initialize PRNGs with fresh entropy. The - /// [`FromEntropy`] trait provides a convenient `from_entropy` method - /// based on `from_rng`. + /// `FromEntropy` trait from [`rand`] crate provides a convenient + /// `from_entropy` method based on `from_rng`. /// /// Usage of this method is not recommended when reproducibility is required /// since implementing PRNGs are not required to fix Endianness and are @@ -354,9 +345,9 @@ pub trait SeedableRng: Sized { /// results if their seed numbers are small or if there is a simple pattern /// between them. /// - /// Prefer to seed from a strong external entropy source like [`OsRng`] or - /// from a cryptographic PRNG; if creating a new generator for cryptographic - /// uses you *must* seed from a strong source. + /// Prefer to seed from a strong external entropy source like `OsRng` from + /// [`rand_os`] crate or from a cryptographic PRNG; if creating a new + /// generator for cryptographic uses you *must* seed from a strong source. /// /// Seeding a small PRNG from another small PRNG is possible, but /// something to be careful with. An extreme example of how this can go @@ -367,8 +358,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. /// - /// [`FromEntropy`]: ../rand/trait.FromEntropy.html - /// [`OsRng`]: ../rand/rngs/struct.OsRng.html + /// [`rand`]: https://docs.rs/rand + /// [`rand_os`]: https://docs.rs/rand_os fn from_rng(mut rng: R) -> Result { let mut seed = Self::Seed::default(); rng.try_fill_bytes(seed.as_mut())?; diff --git a/rand_hc/src/hc128.rs b/rand_hc/src/hc128.rs index d1dadcc9083..6c55ec029f4 100644 --- a/rand_hc/src/hc128.rs +++ b/rand_hc/src/hc128.rs @@ -63,9 +63,6 @@ const SEED_WORDS: usize = 8; // 128 bit key followed by 128 bit iv /// /// [^5]: Internet Engineering Task Force (February 2015), /// ["Prohibiting RC4 Cipher Suites"](https://tools.ietf.org/html/rfc7465). -/// -/// [`BlockRng`]: ../rand_core/block/struct.BlockRng.html -/// [`RngCore`]: ../rand_core/trait.RngCore.html #[derive(Clone, Debug)] pub struct Hc128Rng(BlockRng); diff --git a/rand_isaac/src/isaac.rs b/rand_isaac/src/isaac.rs index 2bfdd943509..7e35ac30ca5 100644 --- a/rand_isaac/src/isaac.rs +++ b/rand_isaac/src/isaac.rs @@ -34,8 +34,8 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN; /// In spite of being designed with cryptographic security in mind, ISAAC hasn't /// been stringently cryptanalyzed and thus cryptographers do not not /// consensually trust it to be secure. When looking for a secure RNG, prefer -/// [`Hc128Rng`] instead, which, like ISAAC, is an array-based RNG and one of -/// the stream-ciphers selected the by eSTREAM contest. +/// `Hc128Rng` from [`rand_hc`] crate instead, which, like ISAAC, is an +/// array-based RNG and one of the stream-ciphers selected the by eSTREAM /// /// In 2006 an improvement to ISAAC was suggested by Jean-Philippe Aumasson, /// named ISAAC+[^3]. But because the specification is not complete, because @@ -86,9 +86,7 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN; /// [^3]: Jean-Philippe Aumasson, [*On the pseudo-random generator ISAAC*]( /// https://eprint.iacr.org/2006/438) /// -/// [`Hc128Rng`]: ../../rand_hc/struct.Hc128Rng.html -/// [`BlockRng`]: ../../rand_core/block/struct.BlockRng.html -/// [`RngCore`]: ../../rand_core/trait.RngCore.html +/// [`rand_hc`]: https://docs.rs/rand_hc #[derive(Clone, Debug)] #[cfg_attr(feature="serde1", derive(Serialize, Deserialize))] pub struct IsaacRng(BlockRng); @@ -142,7 +140,7 @@ impl IsaacRng { } } -/// The core of `IsaacRng`, used with `BlockRng`. +/// The core of [`IsaacRng`], used with [`BlockRng`]. #[derive(Clone)] #[cfg_attr(feature="serde1", derive(Serialize, Deserialize))] pub struct IsaacCore { @@ -165,7 +163,7 @@ impl BlockRngCore for IsaacCore { type Results = IsaacArray; /// Refills the output buffer, `results`. See also the pseudocode desciption - /// of the algorithm in the [`IsaacRng`] documentation. + /// of the algorithm in the `IsaacRng` documentation. /// /// Optimisations used (similar to the reference implementation): /// @@ -183,8 +181,6 @@ impl BlockRngCore for IsaacCore { /// from `results` in reverse. We read them in the normal direction, to /// make `fill_bytes` a memcopy. To maintain compatibility we fill in /// reverse. - /// - /// [`IsaacRng`]: struct.IsaacRng.html fn generate(&mut self, results: &mut IsaacArray) { self.c += w(1); // abbreviations diff --git a/rand_isaac/src/isaac64.rs b/rand_isaac/src/isaac64.rs index 2712762ab32..c1dcda63416 100644 --- a/rand_isaac/src/isaac64.rs +++ b/rand_isaac/src/isaac64.rs @@ -40,8 +40,8 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN; /// In spite of being designed with cryptographic security in mind, ISAAC hasn't /// been stringently cryptanalyzed and thus cryptographers do not not /// consensually trust it to be secure. When looking for a secure RNG, prefer -/// [`Hc128Rng`] instead, which, like ISAAC, is an array-based RNG and one of -/// the stream-ciphers selected the by eSTREAM contest. +/// `Hc128Rng` from [`rand_hc`] crate instead, which, like ISAAC, is an +/// array-based RNG and one of the stream-ciphers selected the by eSTREAM /// /// ## Overview of the ISAAC-64 algorithm: /// (in pseudo-code) @@ -75,10 +75,9 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN; /// [^1]: Bob Jenkins, [*ISAAC and RC4*]( /// http://burtleburtle.net/bob/rand/isaac.html) /// -/// [`IsaacRng`]: ../isaac/struct.IsaacRng.html -/// [`Hc128Rng`]: ../../rand_hc/struct.Hc128Rng.html -/// [`BlockRng64`]: ../../rand_core/block/struct.BlockRng64.html -/// [`RngCore`]: ../../rand_core/trait.RngCore.html +/// [`IsaacRng`]: crate::isaac::IsaacRng +/// [`rand_hc`]: https://docs.rs/rand_hc +/// [`BlockRng64`]: rand_core::block::BlockRng64 #[derive(Clone, Debug)] #[cfg_attr(feature="serde1", derive(Serialize, Deserialize))] pub struct Isaac64Rng(BlockRng64); @@ -155,7 +154,7 @@ impl BlockRngCore for Isaac64Core { type Results = IsaacArray; /// Refills the output buffer, `results`. See also the pseudocode desciption - /// of the algorithm in the [`Isaac64Rng`] documentation. + /// of the algorithm in the `Isaac64Rng` documentation. /// /// Optimisations used (similar to the reference implementation): /// @@ -173,8 +172,6 @@ impl BlockRngCore for Isaac64Core { /// from `results` in reverse. We read them in the normal direction, to /// make `fill_bytes` a memcopy. To maintain compatibility we fill in /// reverse. - /// - /// [`Isaac64Rng`]: struct.Isaac64Rng.html fn generate(&mut self, results: &mut IsaacArray) { self.c += w(1); // abbreviations diff --git a/rand_os/src/lib.rs b/rand_os/src/lib.rs index 67b0dfe40b2..907c6298d47 100644 --- a/rand_os/src/lib.rs +++ b/rand_os/src/lib.rs @@ -9,7 +9,7 @@ //! Interface to the random number generator of the operating system. //! -//! `OsRng` is the preferred external source of entropy for most applications. +//! [`OsRng`] 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`. //! @@ -17,7 +17,7 @@ //! not entirely theoretical, for `OsRng` to fail. In such cases [`EntropyRng`] //! falls back on a good alternative entropy source. //! -//! `OsRng::new()` is guaranteed to be very cheap (after the first successful +//! [`OsRng::new()`] is guaranteed to be very cheap (after the first successful //! call), and will never consume more than one file handle per process. //! //! # Usage example @@ -100,9 +100,8 @@ //! but must eventually panic if the error persists. //! //! [`EntropyRng`]: ../rand/rngs/struct.EntropyRng.html -//! [`RngCore`]: ../rand_core/trait.RngCore.html -//! [`try_fill_bytes`]: ../rand_core/trait.RngCore.html#method.tymethod.try_fill_bytes -//! [`ErrorKind::NotReady`]: ../rand_core/enum.ErrorKind.html#variant.NotReady +//! [`try_fill_bytes`]: RngCore::try_fill_bytes +//! [`ErrorKind::NotReady`]: rand_core::ErrorKind //! //! [1]: http://man7.org/linux/man-pages/man2/getrandom.2.html //! [2]: http://man7.org/linux/man-pages/man4/urandom.4.html diff --git a/rand_xoshiro/src/lib.rs b/rand_xoshiro/src/lib.rs index 634db3145c0..e63411c6551 100644 --- a/rand_xoshiro/src/lib.rs +++ b/rand_xoshiro/src/lib.rs @@ -55,17 +55,6 @@ //! //! [xoshiro]: http://xoshiro.di.unimi.it/ //! [low linear complexity]: http://xoshiro.di.unimi.it/lowcomp.php -//! [`Xoshiro256StarStar`]: ./struct.Xoshiro256StarStar.html -//! [`Xoshiro256Plus`]: ./struct.Xoshiro256Plus.html -//! [`Xoroshiro128StarStar`]: ./struct.Xoroshiro128StarStar.html -//! [`Xoroshiro128Plus`]: ./struct.Xoroshiro128Plus.html -//! [`Xoshiro512StarStar`]: ./struct.Xoshiro512StarStar.html -//! [`Xoshiro512Plus`]: ./struct.Xoshiro512Plus.html -//! [`SplitMix64`]: ./struct.SplitMix64.html -//! [`Xoshiro128StarStar`]: ./struct.Xoshiro128StarStar.html -//! [`Xoshiro128Plus`]: ./struct.Xoshiro128Plus.html -//! [`Xoroshiro64StarStar`]: ./struct.Xoroshiro64StarStar.html -//! [`Xoroshiro64Star`]: ./struct.Xoroshiro64Star.html #![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png", html_favicon_url = "https://www.rust-lang.org/favicon.ico", diff --git a/src/distributions/exponential.rs b/src/distributions/exponential.rs index a7d05005373..76752a60e3d 100644 --- a/src/distributions/exponential.rs +++ b/src/distributions/exponential.rs @@ -64,7 +64,7 @@ impl Distribution for Exp1 { /// This distribution has density function: `f(x) = lambda * exp(-lambda * x)` /// for `x > 0`. /// -/// Note that [`Exp1`](struct.Exp1.html) is an optimised implementation for `lambda = 1`. +/// Note that [`Exp1`][crate::distributions::Exp1] is an optimised implementation for `lambda = 1`. /// /// # Example /// diff --git a/src/distributions/float.rs b/src/distributions/float.rs index ece12f572b8..0dd5caa4a8b 100644 --- a/src/distributions/float.rs +++ b/src/distributions/float.rs @@ -36,9 +36,9 @@ use packed_simd::*; /// println!("f32 from (0, 1): {}", val); /// ``` /// -/// [`Standard`]: struct.Standard.html -/// [`Open01`]: struct.Open01.html -/// [`Uniform`]: uniform/struct.Uniform.html +/// [`Standard`]: crate::distributions::Standard +/// [`Open01`]: crate::distributions::Open01 +/// [`Uniform`]: crate::distributions::uniform::Uniform #[derive(Clone, Copy, Debug)] pub struct OpenClosed01; @@ -62,9 +62,9 @@ pub struct OpenClosed01; /// println!("f32 from (0, 1): {}", val); /// ``` /// -/// [`Standard`]: struct.Standard.html -/// [`OpenClosed01`]: struct.OpenClosed01.html -/// [`Uniform`]: uniform/struct.Uniform.html +/// [`Standard`]: crate::distributions::Standard +/// [`OpenClosed01`]: crate::distributions::OpenClosed01 +/// [`Uniform`]: crate::distributions::uniform::Uniform #[derive(Clone, Copy, Debug)] pub struct Open01; diff --git a/src/distributions/mod.rs b/src/distributions/mod.rs index 5e879cbd9fa..6e2d6c7bad2 100644 --- a/src/distributions/mod.rs +++ b/src/distributions/mod.rs @@ -56,7 +56,7 @@ //! //! User types `T` may also implement `Distribution` for [`Uniform`], //! although this is less straightforward than for [`Standard`] (see the -//! documentation in the [`uniform` module]. Doing so enables generation of +//! documentation in the [`uniform`] module. Doing so enables generation of //! values of type `T` with [`Rng::gen_range`]. //! //! @@ -65,8 +65,8 @@ //! There are surprisingly many ways to uniformly generate random floats. A //! range between 0 and 1 is standard, but the exact bounds (open vs closed) //! and accuracy differ. In addition to the [`Standard`] distribution Rand offers -//! [`Open01`] and [`OpenClosed01`]. See [Floating point implementation] for -//! more details. +//! [`Open01`] and [`OpenClosed01`]. See "Floating point implementation" section of +//! [`Standard`] documentation for more details. //! //! [`Alphanumeric`] is a simple distribution to sample random letters and //! numbers of the `char` type; in contrast [`Standard`] may sample any valid @@ -140,47 +140,38 @@ //! //! //! [probability distribution]: https://en.wikipedia.org/wiki/Probability_distribution -//! [`Distribution`]: trait.Distribution.html -//! [`gen_range`]: ../trait.Rng.html#method.gen_range -//! [`gen`]: ../trait.Rng.html#method.gen -//! [`sample`]: ../trait.Rng.html#method.sample -//! [`new_inclusive`]: struct.Uniform.html#method.new_inclusive -//! [`random()`]: ../fn.random.html -//! [`Rng::gen_bool`]: ../trait.Rng.html#method.gen_bool -//! [`Rng::gen_range`]: ../trait.Rng.html#method.gen_range -//! [`Rng::gen()`]: ../trait.Rng.html#method.gen -//! [`Rng`]: ../trait.Rng.html -//! [`uniform` module]: uniform/index.html -//! [Floating point implementation]: struct.Standard.html#floating-point-implementation -// distributions -//! [`Alphanumeric`]: struct.Alphanumeric.html -//! [`Bernoulli`]: struct.Bernoulli.html -//! [`Beta`]: struct.Beta.html -//! [`Binomial`]: struct.Binomial.html -//! [`Cauchy`]: struct.Cauchy.html -//! [`ChiSquared`]: struct.ChiSquared.html -//! [`Dirichlet`]: struct.Dirichlet.html -//! [`Exp`]: struct.Exp.html -//! [`Exp1`]: struct.Exp1.html -//! [`FisherF`]: struct.FisherF.html -//! [`Gamma`]: struct.Gamma.html -//! [`LogNormal`]: struct.LogNormal.html -//! [`Normal`]: struct.Normal.html -//! [`Open01`]: struct.Open01.html -//! [`OpenClosed01`]: struct.OpenClosed01.html -//! [`Pareto`]: struct.Pareto.html -//! [`Poisson`]: struct.Poisson.html -//! [`Standard`]: struct.Standard.html -//! [`StandardNormal`]: struct.StandardNormal.html -//! [`StudentT`]: struct.StudentT.html -//! [`Triangular`]: struct.Triangular.html -//! [`Uniform`]: struct.Uniform.html -//! [`Uniform::new`]: struct.Uniform.html#method.new -//! [`Uniform::new_inclusive`]: struct.Uniform.html#method.new_inclusive -//! [`UnitSphereSurface`]: struct.UnitSphereSurface.html -//! [`UnitCircle`]: struct.UnitCircle.html -//! [`Weibull`]: struct.Weibull.html -//! [`WeightedIndex`]: struct.WeightedIndex.html +//! [`gen_range`]: Rng::gen_range +//! [`gen`]: Rng::gen +//! [`sample`]: Rng::sample +//! [`new_inclusive`]: Uniform::new_inclusive +//! [`Alphanumeric`]: distributions::Alphanumeric +//! [`Bernoulli`]: distributions::Bernoulli +//! [`Beta`]: distributions::Beta +//! [`Binomial`]: distributions::Binomial +//! [`Cauchy`]: distributions::Cauchy +//! [`ChiSquared`]: distributions::ChiSquared +//! [`Dirichlet`]: distributions::Dirichlet +//! [`Exp`]: distributions::Exp +//! [`Exp1`]: distributions::Exp1 +//! [`FisherF`]: distributions::FisherF +//! [`Gamma`]: distributions::Gamma +//! [`LogNormal`]: distributions::LogNormal +//! [`Normal`]: distributions::Normal +//! [`Open01`]: distributions::Open01 +//! [`OpenClosed01`]: distributions::OpenClosed01 +//! [`Pareto`]: distributions::Pareto +//! [`Poisson`]: distributions::Poisson +//! [`Standard`]: distributions::Standard +//! [`StandardNormal`]: distributions::StandardNormal +//! [`StudentT`]: distributions::StudentT +//! [`Triangular`]: distributions::Triangular +//! [`Uniform`]: distributions::Uniform +//! [`Uniform::new`]: distributions::Uniform::new +//! [`Uniform::new_inclusive`]: distributions::Uniform::new_inclusive +//! [`UnitSphereSurface`]: distributions::UnitSphereSurface +//! [`UnitCircle`]: distributions::UnitCircle +//! [`Weibull`]: distributions::Weibull +//! [`WeightedIndex`]: distributions::WeightedIndex #[cfg(any(rustc_1_26, features="nightly"))] use core::iter; @@ -238,8 +229,7 @@ mod utils; /// advantage of not needing to consider thread safety, and for most /// distributions efficient state-less sampling algorithms are available. /// -/// [`Rng`]: ../trait.Rng.html -/// [`sample_iter`]: trait.Distribution.html#method.sample_iter +/// [`sample_iter`]: Distribution::method.sample_iter pub trait Distribution { /// Generate a random value of `T`, using `rng` as the source of randomness. fn sample(&self, rng: &mut R) -> T; @@ -292,8 +282,7 @@ impl<'a, T, D: Distribution> Distribution for &'a D { /// This `struct` is created by the [`sample_iter`] method on [`Distribution`]. /// See its documentation for more. /// -/// [`Distribution`]: trait.Distribution.html -/// [`sample_iter`]: trait.Distribution.html#method.sample_iter +/// [`sample_iter`]: Distribution::sample_iter #[derive(Debug)] pub struct DistIter<'a, D: 'a, R: 'a, T> { distr: &'a D, @@ -379,9 +368,7 @@ impl<'a, D, R, T> iter::TrustedLen for DistIter<'a, D, R, T> /// faster on some architectures (on modern Intel CPUs all methods have /// approximately equal performance). /// -/// [`Open01`]: struct.Open01.html -/// [`OpenClosed01`]: struct.OpenClosed01.html -/// [`Uniform`]: uniform/struct.Uniform.html +/// [`Uniform`]: uniform::Uniform #[derive(Clone, Copy, Debug)] pub struct Standard; @@ -401,7 +388,7 @@ pub struct Weighted { /// /// Deprecated: use [`WeightedIndex`] instead. /// -/// [`WeightedIndex`]: struct.WeightedIndex.html +/// [`WeightedIndex`]: WeightedIndex #[deprecated(since="0.6.0", note="use WeightedIndex instead")] #[allow(deprecated)] #[derive(Debug)] diff --git a/src/distributions/normal.rs b/src/distributions/normal.rs index b8d632e62c5..089865e0ad1 100644 --- a/src/distributions/normal.rs +++ b/src/distributions/normal.rs @@ -91,7 +91,7 @@ impl Distribution for StandardNormal { /// println!("{} is from a N(2, 9) distribution", v) /// ``` /// -/// [`StandardNormal`]: struct.StandardNormal.html +/// [`StandardNormal`]: crate::distributions::StandardNormal #[derive(Clone, Copy, Debug)] pub struct Normal { mean: f64, diff --git a/src/distributions/uniform.rs b/src/distributions/uniform.rs index ceed77dbef6..19b49345b37 100644 --- a/src/distributions/uniform.rs +++ b/src/distributions/uniform.rs @@ -15,13 +15,13 @@ //! [`Uniform`]. //! //! This distribution is provided with support for several primitive types -//! (all integer and floating-point types) as well as `std::time::Duration`, +//! (all integer and floating-point types) as well as [`std::time::Duration`], //! and supports extension to user-defined types via a type-specific *back-end* //! implementation. //! //! The types [`UniformInt`], [`UniformFloat`] and [`UniformDuration`] are the //! back-ends supporting sampling from primitive integer and floating-point -//! ranges as well as from `std::time::Duration`; these types do not normally +//! ranges as well as from [`std::time::Duration`]; these types do not normally //! need to be used directly (unless implementing a derived back-end). //! //! # Example usage @@ -100,14 +100,12 @@ //! let x = uniform.sample(&mut thread_rng()); //! ``` //! -//! [`Uniform`]: struct.Uniform.html -//! [`Rng::gen_range`]: ../../trait.Rng.html#method.gen_range -//! [`SampleUniform`]: trait.SampleUniform.html -//! [`UniformSampler`]: trait.UniformSampler.html -//! [`UniformInt`]: struct.UniformInt.html -//! [`UniformFloat`]: struct.UniformFloat.html -//! [`UniformDuration`]: struct.UniformDuration.html -//! [`SampleBorrow::borrow`]: trait.SampleBorrow.html#method.borrow +//! [`SampleUniform`]: crate::distributions::uniform::SampleUniform +//! [`UniformSampler`]: crate::distributions::uniform::UniformSampler +//! [`UniformInt`]: crate::distributions::uniform::UniformInt +//! [`UniformFloat`]: crate::distributions::uniform::UniformFloat +//! [`UniformDuration`]: crate::distributions::uniform::UniformDuration +//! [`SampleBorrow::borrow`]: crate::distributions::uniform::SampleBorrow::borrow #[cfg(feature = "std")] use std::time::Duration; @@ -165,10 +163,8 @@ use packed_simd::*; /// } /// ``` /// -/// [`Uniform::new`]: struct.Uniform.html#method.new -/// [`Uniform::new_inclusive`]: struct.Uniform.html#method.new_inclusive -/// [`new`]: struct.Uniform.html#method.new -/// [`new_inclusive`]: struct.Uniform.html#method.new_inclusive +/// [`new`]: Uniform::new +/// [`new_inclusive`]: Uniform::new_inclusive #[derive(Clone, Copy, Debug)] pub struct Uniform { inner: X::Sampler, @@ -206,9 +202,7 @@ impl Distribution for Uniform { /// See the [module documentation] on how to implement [`Uniform`] range /// sampling for a custom type. /// -/// [`UniformSampler`]: trait.UniformSampler.html -/// [module documentation]: index.html -/// [`Uniform`]: struct.Uniform.html +/// [module documentation]: crate::distributions::uniform pub trait SampleUniform: Sized { /// The `UniformSampler` implementation supporting type `X`. type Sampler: UniformSampler; @@ -222,9 +216,8 @@ pub trait SampleUniform: Sized { /// Implementation of [`sample_single`] is optional, and is only useful when /// the implementation can be faster than `Self::new(low, high).sample(rng)`. /// -/// [module documentation]: index.html -/// [`Uniform`]: struct.Uniform.html -/// [`sample_single`]: trait.UniformSampler.html#method.sample_single +/// [module documentation]: crate::distributions::uniform +/// [`sample_single`]: UniformSampler::sample_single pub trait UniformSampler: Sized { /// The type sampled by this implementation. type X; @@ -288,11 +281,11 @@ impl From<::core::ops::RangeInclusive> for Uniform { /// only for SampleUniform and references to SampleUniform in /// order to resolve ambiguity issues. /// -/// [`Borrow`]: https://doc.rust-lang.org/std/borrow/trait.Borrow.html +/// [`Borrow`]: std::borrow::Borrow pub trait SampleBorrow { /// Immutably borrows from an owned value. See [`Borrow::borrow`] /// - /// [`Borrow::borrow`]: https://doc.rust-lang.org/std/borrow/trait.Borrow.html#tymethod.borrow + /// [`Borrow::borrow`]: std::borrow::Borrow::borrow fn borrow(&self) -> &Borrowed; } impl SampleBorrow for Borrowed where Borrowed: SampleUniform { @@ -345,9 +338,6 @@ impl<'a, Borrowed> SampleBorrow for &'a Borrowed where Borrowed: Sampl /// An alternative to using a modulus is widening multiply: After a widening /// multiply by `range`, the result is in the high word. Then comparing the low /// word against `zone` makes sure our distribution is uniform. -/// -/// [`UniformSampler`]: trait.UniformSampler.html -/// [`Uniform`]: struct.Uniform.html #[derive(Clone, Copy, Debug)] pub struct UniformInt { low: X, @@ -646,11 +636,9 @@ uniform_simd_int_impl! { /// multiply and addition. Values produced this way have what equals 22 bits of /// random digits for an `f32`, and 52 for an `f64`. /// -/// [`UniformSampler`]: trait.UniformSampler.html -/// [`new`]: trait.UniformSampler.html#tymethod.new -/// [`new_inclusive`]: trait.UniformSampler.html#tymethod.new_inclusive -/// [`Uniform`]: struct.Uniform.html -/// [`Standard`]: ../struct.Standard.html +/// [`new`]: UniformSampler::new +/// [`new_inclusive`]: UniformSampler::new_inclusive +/// [`Standard`]: crate::distributions::Standard #[derive(Clone, Copy, Debug)] pub struct UniformFloat { low: X, @@ -833,9 +821,6 @@ uniform_float_impl! { f64x8, u64x8, f64, u64, 64 - 52 } /// /// Unless you are implementing [`UniformSampler`] for your own types, this type /// should not be used directly, use [`Uniform`] instead. -/// -/// [`UniformSampler`]: trait.UniformSampler.html -/// [`Uniform`]: struct.Uniform.html #[cfg(any(feature = "std", rustc_1_25))] #[derive(Clone, Copy, Debug)] pub struct UniformDuration { diff --git a/src/distributions/weighted.rs b/src/distributions/weighted.rs index 01c8fe668e0..9b83aa91655 100644 --- a/src/distributions/weighted.rs +++ b/src/distributions/weighted.rs @@ -40,9 +40,9 @@ use core::fmt; /// `N` is the number of weights. /// /// Sampling from `WeightedIndex` will result in a single call to -/// [`Uniform::sample`], which typically will request a single value from -/// the underlying [`RngCore`], though the exact number depends on the -/// implementaiton of [`Uniform::sample`]. +/// `Uniform::sample` (method of [`Distribution`] trait), which typically +/// will request a single value from the underlying [`RngCore`], though the +/// exact number depends on the implementaiton of `Uniform::sample`. /// /// # Example /// @@ -67,9 +67,8 @@ use core::fmt; /// } /// ``` /// -/// [`Uniform`]: struct.Uniform.html -/// [`Uniform::sample`]: struct.Uniform.html#method.sample -/// [`RngCore`]: ../trait.RngCore.html +/// [`Uniform`]: crate::distributions::uniform::Uniform +/// [`RngCore`]: rand_core::RngCore #[derive(Debug, Clone)] pub struct WeightedIndex { cumulative_weights: Vec, @@ -84,8 +83,7 @@ impl WeightedIndex { /// Returns an error if the iterator is empty, if any weight is `< 0`, or /// if its total value is 0. /// - /// [`Distribution`]: trait.Distribution.html - /// [`Uniform`]: struct.Uniform.html + /// [`Uniform`]: crate::distributions::uniform::Uniform pub fn new(weights: I) -> Result, WeightedError> where I: IntoIterator, I::Item: SampleBorrow, diff --git a/src/lib.rs b/src/lib.rs index ca231b5dbb8..491eb7ecd90 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -17,7 +17,7 @@ //! To get you started quickly, the easiest and highest-level way to get //! a random value is to use [`random()`]; alternatively you can use //! [`thread_rng()`]. The [`Rng`] trait provides a useful API on all RNGs, while -//! the [`distributions` module] and [`seq` module] provide further +//! the [`distributions`] and [`seq`] modules provide further //! functionality on top of RNGs. //! //! ``` @@ -39,12 +39,6 @@ //! //! For the user guide and futher documentation, please read //! [The Rust Rand Book](https://rust-random.github.io/book). -//! -//! [`distributions` module]: distributions/index.html -//! [`random()`]: fn.random.html -//! [`Rng`]: trait.Rng.html -//! [`seq` module]: seq/index.html -//! [`thread_rng()`]: fn.thread_rng.html #![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png", @@ -200,12 +194,10 @@ use distributions::uniform::{SampleUniform, UniformSampler, SampleBorrow}; /// /// # let v = foo(&mut thread_rng()); /// ``` -/// -/// [`RngCore`]: trait.RngCore.html pub trait Rng: RngCore { /// Return a random value supporting the [`Standard`] distribution. /// - /// [`Standard`]: distributions/struct.Standard.html + /// [`Standard`]: distributions::Standard /// /// # Example /// @@ -245,7 +237,7 @@ pub trait Rng: RngCore { /// println!("{}", m); /// ``` /// - /// [`Uniform`]: distributions/uniform/struct.Uniform.html + /// [`Uniform`]: distributions::uniform::Uniform fn gen_range(&mut self, low: B1, high: B2) -> T where B1: SampleBorrow + Sized, B2: SampleBorrow + Sized { @@ -323,9 +315,8 @@ pub trait Rng: RngCore { /// thread_rng().fill(&mut arr[..]); /// ``` /// - /// [`fill_bytes`]: trait.RngCore.html#method.fill_bytes - /// [`try_fill`]: trait.Rng.html#method.try_fill - /// [`AsByteSliceMut`]: trait.AsByteSliceMut.html + /// [`fill_bytes`]: RngCore::fill_bytes + /// [`try_fill`]: Rng::try_fill fn fill(&mut self, dest: &mut T) { self.fill_bytes(dest.as_byte_slice_mut()); dest.to_le(); @@ -358,10 +349,8 @@ pub trait Rng: RngCore { /// # try_inner().unwrap() /// ``` /// - /// [`ErrorKind`]: enum.ErrorKind.html - /// [`try_fill_bytes`]: trait.RngCore.html#method.try_fill_bytes - /// [`fill`]: trait.Rng.html#method.fill - /// [`AsByteSliceMut`]: trait.AsByteSliceMut.html + /// [`try_fill_bytes`]: RngCore::try_fill_bytes + /// [`fill`]: Rng::fill fn try_fill(&mut self, dest: &mut T) -> Result<(), Error> { self.try_fill_bytes(dest.as_byte_slice_mut())?; dest.to_le(); @@ -386,7 +375,7 @@ pub trait Rng: RngCore { /// /// If `p < 0` or `p > 1`. /// - /// [`Bernoulli`]: distributions/bernoulli/struct.Bernoulli.html + /// [`Bernoulli`]: distributions::bernoulli::Bernoulli #[inline] fn gen_bool(&mut self, p: f64) -> bool { let d = distributions::Bernoulli::new(p); @@ -415,7 +404,7 @@ pub trait Rng: RngCore { /// println!("{}", rng.gen_ratio(2, 3)); /// ``` /// - /// [`Bernoulli`]: distributions/bernoulli/struct.Bernoulli.html + /// [`Bernoulli`]: distributions::bernoulli::Bernoulli #[inline] fn gen_ratio(&mut self, numerator: u32, denominator: u32) -> bool { let d = distributions::Bernoulli::from_ratio(numerator, denominator); @@ -424,9 +413,7 @@ pub trait Rng: RngCore { /// Return a random element from `values`. /// - /// Deprecated: use [`SliceRandom::choose`] instead. - /// - /// [`SliceRandom::choose`]: seq/trait.SliceRandom.html#method.choose + /// Deprecated: use [`seq::SliceRandom::choose`] instead. #[deprecated(since="0.6.0", note="use SliceRandom::choose instead")] fn choose<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T> { use seq::SliceRandom; @@ -435,9 +422,7 @@ pub trait Rng: RngCore { /// Return a mutable pointer to a random element from `values`. /// - /// Deprecated: use [`SliceRandom::choose_mut`] instead. - /// - /// [`SliceRandom::choose_mut`]: seq/trait.SliceRandom.html#method.choose_mut + /// Deprecated: use [`seq::SliceRandom::choose_mut`] instead. #[deprecated(since="0.6.0", note="use SliceRandom::choose_mut instead")] fn choose_mut<'a, T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T> { use seq::SliceRandom; @@ -446,9 +431,7 @@ pub trait Rng: RngCore { /// Shuffle a mutable slice in place. /// - /// Deprecated: use [`SliceRandom::shuffle`] instead. - /// - /// [`SliceRandom::shuffle`]: seq/trait.SliceRandom.html#method.shuffle + /// Deprecated: use [`seq::SliceRandom::shuffle`] instead. #[deprecated(since="0.6.0", note="use SliceRandom::shuffle instead")] fn shuffle(&mut self, values: &mut [T]) { use seq::SliceRandom; @@ -460,10 +443,7 @@ impl Rng for R {} /// Trait for casting types to byte slices /// -/// This is used by the [`fill`] and [`try_fill`] methods. -/// -/// [`fill`]: trait.Rng.html#method.fill -/// [`try_fill`]: trait.Rng.html#method.try_fill +/// This is used by the [`Rng::fill`] and [`Rng::try_fill`] methods. pub trait AsByteSliceMut { /// Return a mutable reference to self as a byte slice fn as_byte_slice_mut(&mut self) -> &mut [u8]; @@ -580,9 +560,7 @@ impl_as_byte_slice_arrays!(!div 4096, N,N,N,N,N,N,N,); /// println!("Random die roll: {}", rng.gen_range(1, 7)); /// ``` /// -/// [`EntropyRng`]: rngs/struct.EntropyRng.html -/// [`SeedableRng`]: trait.SeedableRng.html -/// [`SeedableRng::from_seed`]: trait.SeedableRng.html#tymethod.from_seed +/// [`EntropyRng`]: rngs::EntropyRng #[cfg(feature="std")] pub trait FromEntropy: SeedableRng { /// Creates a new instance, automatically seeded with fresh entropy. @@ -667,8 +645,7 @@ impl FromEntropy for R { /// } /// ``` /// -/// [`thread_rng`]: fn.thread_rng.html -/// [`Standard`]: distributions/struct.Standard.html +/// [`Standard`]: distributions::Standard #[cfg(feature="std")] #[inline] pub fn random() -> T where Standard: Distribution { diff --git a/src/rngs/adapter/read.rs b/src/rngs/adapter/read.rs index 30b6de63647..9b9c18b3ebc 100644 --- a/src/rngs/adapter/read.rs +++ b/src/rngs/adapter/read.rs @@ -15,7 +15,7 @@ use rand_core::{RngCore, Error, ErrorKind, impls}; /// An RNG that reads random bytes straight from any type supporting -/// `std::io::Read`, for example files. +/// [`std::io::Read`], for example files. /// /// This will work best with an infinite reader, but that is not required. /// @@ -24,10 +24,10 @@ use rand_core::{RngCore, Error, ErrorKind, impls}; /// /// # Panics /// -/// `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. +/// `ReadRng` uses [`std::io::Read::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. /// /// # Example /// @@ -40,9 +40,8 @@ use rand_core::{RngCore, Error, ErrorKind, impls}; /// println!("{:x}", rng.gen::()); /// ``` /// -/// [`OsRng`]: ../struct.OsRng.html -/// [`RngCore`]: ../../trait.RngCore.html -/// [`try_fill_bytes`]: ../../trait.RngCore.html#method.tymethod.try_fill_bytes +/// [`OsRng`]: rand_os::OsRng +/// [`try_fill_bytes`]: RngCore::try_fill_bytes #[derive(Debug)] pub struct ReadRng { reader: R diff --git a/src/rngs/adapter/reseeding.rs b/src/rngs/adapter/reseeding.rs index 016afab381c..ed2aab4cffa 100644 --- a/src/rngs/adapter/reseeding.rs +++ b/src/rngs/adapter/reseeding.rs @@ -79,11 +79,11 @@ use rand_core::block::{BlockRngCore, BlockRng}; /// # } /// ``` /// -/// [`ChaChaCore`]: ../../../rand_chacha/struct.ChaChaCore.html -/// [`Hc128Core`]: ../../../rand_hc/struct.Hc128Core.html -/// [`BlockRngCore`]: ../../../rand_core/block/trait.BlockRngCore.html -/// [`ReseedingRng::new`]: struct.ReseedingRng.html#method.new -/// [`reseed()`]: struct.ReseedingRng.html#method.reseed +/// [`ChaChaCore`]: rand_chacha::ChaChaCore +/// [`Hc128Core`]: rand_hc::Hc128Core +/// [`BlockRngCore`]: rand_core::block::BlockRngCore +/// [`ReseedingRng::new`]: ReseedingRng::new +/// [`reseed()`]: ReseedingRng::reseed #[derive(Debug)] pub struct ReseedingRng(BlockRng>) where R: BlockRngCore + SeedableRng, diff --git a/src/rngs/entropy.rs b/src/rngs/entropy.rs index 372b4d75473..9a2affdffc1 100644 --- a/src/rngs/entropy.rs +++ b/src/rngs/entropy.rs @@ -38,11 +38,10 @@ use rngs; /// report the error, and only the one from `OsRng`. The other [`RngCore`] /// methods will panic in case of an error. /// -/// [`OsRng`]: struct.OsRng.html -/// [`JitterRng`]: jitter/struct.JitterRng.html -/// [`thread_rng`]: ../fn.thread_rng.html -/// [`RngCore`]: ../trait.RngCore.html -/// [`try_fill_bytes`]: ../trait.RngCore.html#method.tymethod.try_fill_bytes +/// [`OsRng`]: rand_os::OsRng +/// [`thread_rng`]: crate::thread_rng +/// [`JitterRng`]: crate::rngs::JitterRng +/// [`try_fill_bytes`]: RngCore::try_fill_bytes #[derive(Debug)] pub struct EntropyRng { source: Source, diff --git a/src/rngs/jitter.rs b/src/rngs/jitter.rs index 3e93477d956..fa6701ec754 100644 --- a/src/rngs/jitter.rs +++ b/src/rngs/jitter.rs @@ -129,10 +129,9 @@ const MEMORY_SIZE: usize = MEMORY_BLOCKS * MEMORY_BLOCKSIZE; /// restart.py -v -u 4 jitter_rng_min.bin 4 /// ``` /// -/// [`OsRng`]: struct.OsRng.html -/// [`JitterRng::new()`]: struct.JitterRng.html#method.new -/// [`new_with_timer`]: struct.JitterRng.html#method.new_with_timer -/// [`timer_stats`]: struct.JitterRng.html#method.timer_stats +/// [`OsRng`]: rand_os::OsRng +/// [`new_with_timer`]: JitterRng::new_with_timer +/// [`timer_stats`]: JitterRng::timer_stats pub struct JitterRng { data: u64, // Actual random number // Number of rounds to run the entropy collector per 64 bits @@ -217,7 +216,7 @@ impl Clone for JitterRng { /// An error that can occur when [`JitterRng::test_timer`] fails. /// -/// [`JitterRng::test_timer`]: struct.JitterRng.html#method.test_timer +/// [`JitterRng::test_timer`]: JitterRng::test_timer #[derive(Debug, Clone, PartialEq, Eq)] pub enum TimerError { /// No timer available. @@ -274,7 +273,7 @@ impl From for Error { static JITTER_ROUNDS: AtomicUsize = ATOMIC_USIZE_INIT; impl JitterRng { - /// Create a new `JitterRng`. Makes use of `std::time` for a timer, or a + /// Create a new `JitterRng`. Makes use of [`std::time`] for a timer, or a /// platform-specific function with higher accuracy if necessary and /// available. /// @@ -342,8 +341,8 @@ impl JitterRng { /// # let _ = try_inner(); /// ``` /// - /// [`test_timer`]: struct.JitterRng.html#method.test_timer - /// [`set_rounds`]: struct.JitterRng.html#method.set_rounds + /// [`test_timer`]: JitterRng::test_timer + /// [`set_rounds`]: JitterRng::set_rounds pub fn new_with_timer(timer: fn() -> u64) -> JitterRng { JitterRng { data: 0, @@ -363,7 +362,7 @@ impl JitterRng { /// rounds required for full strength (platform dependent), so one may use /// `rng.set_rounds(rng.test_timer()?);` or cache the value. /// - /// [`new_with_timer`]: struct.JitterRng.html#method.new_with_timer + /// [`new_with_timer`]: JitterRng::new_with_timer pub fn set_rounds(&mut self, rounds: u8) { assert!(rounds > 0); self.rounds = rounds; @@ -607,8 +606,6 @@ impl JitterRng { /// If succesful, this will return the estimated number of rounds necessary /// to collect 64 bits of entropy. Otherwise a [`TimerError`] with the cause /// of the failure will be returned. - /// - /// [`TimerError`]: enum.TimerError.html pub fn test_timer(&mut self) -> Result { debug!("JitterRng: testing timer ..."); // We could add a check for system capabilities such as `clock_getres` @@ -758,8 +755,8 @@ impl JitterRng { /// of entropy one round of the entropy collector can collect in the worst /// case. /// - /// See [Quality testing](struct.JitterRng.html#quality-testing) on how to - /// use `timer_stats` to test the quality of `JitterRng`. + /// See this crate README on how to use `timer_stats` to test the quality + /// of `JitterRng`. pub fn timer_stats(&mut self, var_rounds: bool) -> i64 { let mut mem = [0; MEMORY_SIZE]; diff --git a/src/rngs/mod.rs b/src/rngs/mod.rs index 847fc943529..5630597532c 100644 --- a/src/rngs/mod.rs +++ b/src/rngs/mod.rs @@ -53,7 +53,7 @@ //! which is one of the recommendations by ECRYPT's eSTREAM project. //! //! The above PRNGs do not cover all use-cases; more algorithms can be found in -//! the [`prng` module], as well as in several other crates. For example, you +//! the [`prng`][crate::prng] module, as well as in several other crates. For example, you //! may wish a CSPRNG with significantly lower memory usage than [`StdRng`] //! while being less concerned about performance, in which case [`ChaChaRng`] //! is a good choice. @@ -83,19 +83,19 @@ //! to reproduce the output sequence by using a fixed seed. (Don't use //! [`StdRng`] or [`SmallRng`] in this case since different algorithms may be //! used by future versions of Rand; use an algorithm from the -//! [`prng` module].) +//! [`prng`] module.) //! //! ## Conclusion //! //! - [`thread_rng`] is what you often want to use. //! - If you want more control, flexibility, or better performance, use -//! [`StdRng`], [`SmallRng`] or an algorithm from the [`prng` module]. +//! [`StdRng`], [`SmallRng`] or an algorithm from the [`prng`] module. //! - Use [`FromEntropy::from_entropy`] to seed new PRNGs. //! - If you need reproducibility, use [`SeedableRng::from_seed`] combined with //! a named PRNG. //! //! More information and notes on cryptographic security can be found -//! in the [`prng` module]. +//! in the [`prng`] module. //! //! ## Examples //! @@ -135,30 +135,16 @@ //! [`CryptoRng`] is a marker trait cryptographically secure PRNGs can //! implement. //! -//! -// This module: -//! [`ThreadRng`]: struct.ThreadRng.html -//! [`StdRng`]: struct.StdRng.html -//! [`SmallRng`]: struct.SmallRng.html -//! [`EntropyRng`]: struct.EntropyRng.html -//! [`OsRng`]: struct.OsRng.html -//! [`JitterRng`]: struct.JitterRng.html -// Other traits and functions: -//! [`rand_core`]: https://crates.io/crates/rand_core -//! [`prng` module]: ../prng/index.html -//! [`CryptoRng`]: ../trait.CryptoRng.html -//! [`FromEntropy`]: ../trait.FromEntropy.html -//! [`FromEntropy::from_entropy`]: ../trait.FromEntropy.html#tymethod.from_entropy -//! [`RngCore`]: ../trait.RngCore.html -//! [`Rng`]: ../trait.Rng.html -//! [`SeedableRng`]: ../trait.SeedableRng.html -//! [`SeedableRng::from_rng`]: ../trait.SeedableRng.html#tymethod.from_rng -//! [`SeedableRng::from_seed`]: ../trait.SeedableRng.html#tymethod.from_seed -//! [`thread_rng`]: ../fn.thread_rng.html -//! [`mock::StepRng`]: mock/struct.StepRng.html -//! [`adapter::ReadRng`]: adapter/struct.ReadRng.html -//! [`adapter::ReseedingRng`]: adapter/struct.ReseedingRng.html -//! [`ChaChaRng`]: ../../rand_chacha/struct.ChaChaRng.html +//! [`OsRng`]: rand_os::OsRng +//! [`SmallRng`]: rngs::SmallRng +//! [`StdRng`]: rngs::StdRng +//! [`ThreadRng`]: rngs::ThreadRng +//! [`EntropyRng`]: rngs::EntropyRng +//! [`JitterRng`]: rngs::JitterRng +//! [`mock::StepRng`]: rngs::mock::StepRng +//! [`adapter::ReadRng`]: rngs::adapter::ReadRng +//! [`adapter::ReseedingRng`]: rngs::adapter::ReseedingRng +//! [`ChaChaRng`]: rand_chacha::ChaChaRng pub mod adapter; diff --git a/src/rngs/small.rs b/src/rngs/small.rs index b652c8c21fe..f27bdacfa97 100644 --- a/src/rngs/small.rs +++ b/src/rngs/small.rs @@ -25,10 +25,10 @@ type Rng = ::rand_pcg::Pcg32; /// 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. Refer to the documentation on the -/// [`prng` module](../prng/index.html). +/// [`prng`][crate::prng] module. /// -/// The current algorithm is [`Pcg64Mcg`] on 64-bit platforms with Rust version -/// 1.26 and later, or [`Pcg32`] otherwise. +/// The current algorithm is [`Pcg64Mcg`][rand_pcg::Pcg64Mcg] on 64-bit platforms with Rust version +/// 1.26 and later, or [`Pcg32`][rand_pcg::Pcg32] otherwise. /// /// # Examples /// @@ -64,11 +64,9 @@ type Rng = ::rand_pcg::Pcg32; /// .collect(); /// ``` /// -/// [`FromEntropy`]: ../trait.FromEntropy.html -/// [`StdRng`]: struct.StdRng.html -/// [`thread_rng`]: ../fn.thread_rng.html -/// [`Pcg64Mcg`]: ../../rand_pcg/type.Pcg64Mcg.html -/// [`Pcg32`]: ../../rand_pcg/type.Pcg32.html +/// [`FromEntropy`]: crate::FromEntropy +/// [`StdRng`]: crate::rngs::StdRng +/// [`thread_rng`]: crate::thread_rng #[derive(Clone, Debug)] pub struct SmallRng(Rng); diff --git a/src/rngs/std.rs b/src/rngs/std.rs index ce1658b1fea..ae6d327c9fb 100644 --- a/src/rngs/std.rs +++ b/src/rngs/std.rs @@ -23,8 +23,8 @@ use rand_hc::Hc128Rng; /// produce different output depending on the architecture. If you require /// reproducible output, use a named RNG, for example [`ChaChaRng`]. /// -/// [HC-128]: ../../rand_hc/struct.Hc128Rng.html -/// [`ChaChaRng`]: ../../rand_chacha/struct.ChaChaRng.html +/// [HC-128]: rand_hc::Hc128Rng +/// [`ChaChaRng`]: rand_chacha::ChaChaRng #[derive(Clone, Debug)] pub struct StdRng(Hc128Rng); diff --git a/src/rngs/thread.rs b/src/rngs/thread.rs index 7977d85818a..f1aa787dc4f 100644 --- a/src/rngs/thread.rs +++ b/src/rngs/thread.rs @@ -64,11 +64,9 @@ const THREAD_RNG_RESEED_THRESHOLD: u64 = 32*1024*1024; // 32 MiB /// Cloning this handle just produces a new reference to the same thread-local /// generator. /// -/// [`thread_rng`]: ../fn.thread_rng.html -/// [`ReseedingRng`]: adapter/struct.ReseedingRng.html -/// [`StdRng`]: struct.StdRng.html -/// [`EntropyRng`]: struct.EntropyRng.html -/// [HC-128]: ../../rand_hc/struct.Hc128Rng.html +/// [`ReseedingRng`]: crate::rngs::adapter::ReseedingRng +/// [`StdRng`]: crate::rngs::StdRng +/// [HC-128]: rand_hc::Hc128Rng #[derive(Clone, Debug)] pub struct ThreadRng { // use of raw pointer implies type is neither Send nor Sync @@ -94,8 +92,6 @@ thread_local!( /// `ThreadRng::default()` equivelent. /// /// For more information see [`ThreadRng`]. -/// -/// [`ThreadRng`]: rngs/struct.ThreadRng.html pub fn thread_rng() -> ThreadRng { ThreadRng { rng: THREAD_RNG_KEY.with(|t| t.get()) } } diff --git a/src/seq/index.rs b/src/seq/index.rs index 3d4df3acd42..a70c7367f85 100644 --- a/src/seq/index.rs +++ b/src/seq/index.rs @@ -39,7 +39,7 @@ impl IndexVec { /// Return the value at the given `index`. /// - /// (Note: we cannot implement `std::ops::Index` because of lifetime + /// (Note: we cannot implement [`std::ops::Index`] because of lifetime /// restrictions.) pub fn index(&self, index: usize) -> usize { match self { diff --git a/src/seq/mod.rs b/src/seq/mod.rs index 99596028a63..d0f83084a66 100644 --- a/src/seq/mod.rs +++ b/src/seq/mod.rs @@ -98,7 +98,7 @@ pub trait SliceRandom { /// // 50% chance to print 'a', 25% chance to print 'b', 25% chance to print 'c' /// println!("{:?}", choices.choose_weighted(&mut rng, |item| item.1).unwrap().0); /// ``` - /// [`choose`]: trait.SliceRandom.html#method.choose + /// [`choose`]: SliceRandom::choose #[cfg(feature = "alloc")] fn choose_weighted(&self, rng: &mut R, weight: F) -> Result<&Self::Item, WeightedError> where R: Rng + ?Sized, @@ -117,8 +117,8 @@ pub trait SliceRandom { /// /// See also [`choose_weighted`]. /// - /// [`choose_mut`]: trait.SliceRandom.html#method.choose_mut - /// [`choose_weighted`]: trait.SliceRandom.html#method.choose_weighted + /// [`choose_mut`]: SliceRandom::choose_mut + /// [`choose_weighted`]: SliceRandom::choose_weighted #[cfg(feature = "alloc")] fn choose_weighted_mut(&mut self, rng: &mut R, weight: F) -> Result<&mut Self::Item, WeightedError> where R: Rng + ?Sized, @@ -181,8 +181,8 @@ pub trait IteratorRandom: Iterator + Sized { /// This likely consumes multiple random numbers, but the exact number /// is unspecified. /// - /// [`choose`]: trait.SliceRandom.html#method.choose - /// [`choose_mut`]: trait.SliceRandom.html#method.choose_mut + /// [`choose`]: SliceRandom::method.choose + /// [`choose_mut`]: SliceRandom::choose_mut fn choose(mut self, rng: &mut R) -> Option where R: Rng + ?Sized { @@ -406,8 +406,7 @@ impl SliceRandom for [T] { impl IteratorRandom for I where I: Iterator + Sized {} -/// Iterator over multiple choices, as returned by [`SliceRandom::choose_multiple]( -/// trait.SliceRandom.html#method.choose_multiple). +/// Iterator over multiple choices, as returned by [`SliceRandom::choose_multiple] #[cfg(feature = "alloc")] #[derive(Debug)] pub struct SliceChooseIter<'a, S: ?Sized + 'a, T: 'a> { @@ -443,8 +442,6 @@ impl<'a, S: Index + ?Sized + 'a, T: 'a> ExactSizeIterator /// Randomly sample `amount` elements from a finite iterator. /// /// Deprecated: use [`IteratorRandom::choose_multiple`] instead. -/// -/// [`IteratorRandom::choose_multiple`]: trait.IteratorRandom.html#method.choose_multiple #[cfg(feature = "alloc")] #[deprecated(since="0.6.0", note="use IteratorRandom::choose_multiple instead")] pub fn sample_iter(rng: &mut R, iterable: I, amount: usize) -> Result, Vec> @@ -470,8 +467,6 @@ pub fn sample_iter(rng: &mut R, iterable: I, amount: usize) -> Result slice.len()` /// /// Deprecated: use [`SliceRandom::choose_multiple`] instead. -/// -/// [`SliceRandom::choose_multiple`]: trait.SliceRandom.html#method.choose_multiple #[cfg(feature = "alloc")] #[deprecated(since="0.6.0", note="use SliceRandom::choose_multiple instead")] pub fn sample_slice(rng: &mut R, slice: &[T], amount: usize) -> Vec @@ -494,8 +489,6 @@ pub fn sample_slice(rng: &mut R, slice: &[T], amount: usize) -> Vec /// Panics if `amount > slice.len()` /// /// Deprecated: use [`SliceRandom::choose_multiple`] instead. -/// -/// [`SliceRandom::choose_multiple`]: trait.SliceRandom.html#method.choose_multiple #[cfg(feature = "alloc")] #[deprecated(since="0.6.0", note="use SliceRandom::choose_multiple instead")] pub fn sample_slice_ref<'a, R, T>(rng: &mut R, slice: &'a [T], amount: usize) -> Vec<&'a T> From 300b84b37f49a9a8d36650e2d69020d1649d173f Mon Sep 17 00:00:00 2001 From: newpavlov Date: Mon, 14 Jan 2019 14:45:48 +0300 Subject: [PATCH 2/3] fix errors --- rand_core/src/block.rs | 22 +++---- rand_core/src/lib.rs | 104 +++++++++++++++++----------------- rand_isaac/src/isaac64.rs | 8 +-- src/distributions/weighted.rs | 2 +- src/rngs/jitter.rs | 4 +- 5 files changed, 70 insertions(+), 70 deletions(-) diff --git a/rand_core/src/block.rs b/rand_core/src/block.rs index c02bab29880..3045b9482f4 100644 --- a/rand_core/src/block.rs +++ b/rand_core/src/block.rs @@ -20,33 +20,33 @@ //! reseeding with very low overhead. //! //! # Example -//! +//! //! ```norun //! use rand_core::block::{BlockRngCore, BlockRng}; -//! +//! //! struct MyRngCore; -//! +//! //! impl BlockRngCore for MyRngCore { //! type Results = [u32; 16]; -//! +//! //! fn generate(&mut self, results: &mut Self::Results) { //! unimplemented!() //! } //! } -//! +//! //! impl SeedableRng for MyRngCore { //! type Seed = unimplemented!(); //! fn from_seed(seed: Self::Seed) -> Self { //! unimplemented!() //! } //! } -//! +//! //! // optionally, also implement CryptoRng for MyRngCore -//! +//! //! // Final RNG. //! type MyRng = BlockRng; //! ``` -//! +//! //! [`BlockRngCore`]: crate::block::BlockRngCore //! [`fill_bytes`]: RngCore::fill_bytes @@ -58,12 +58,12 @@ use impls::{fill_via_u32_chunks, fill_via_u64_chunks}; /// A trait for RNGs which do not generate random numbers individually, but in /// blocks (typically `[u32; N]`). This technique is commonly used by /// cryptographic RNGs to improve performance. -/// +/// /// See the [module][crate::block] documentation for details. pub trait BlockRngCore { /// Results element type, e.g. `u32`. type Item; - + /// Results type. This is the 'block' an RNG implementing `BlockRngCore` /// generates, which will usually be an array like `[u32; 16]`. type Results: AsRef<[Self::Item]> + AsMut<[Self::Item]> + Default; @@ -141,7 +141,7 @@ impl BlockRng { } /// Get the index into the result buffer. - /// + /// /// If this is equal to or larger than the size of the result buffer then /// the buffer is "empty" and `generate()` must be called to produce new /// results. diff --git a/rand_core/src/lib.rs b/rand_core/src/lib.rs index 4239c624429..4b0e6e48b01 100644 --- a/rand_core/src/lib.rs +++ b/rand_core/src/lib.rs @@ -8,23 +8,23 @@ // except according to those terms. //! Random number generation traits -//! +//! //! This crate is mainly of interest to crates publishing implementations of //! [`RngCore`]. Other users are encouraged to use the [`rand`] crate instead //! which re-exports the main traits and error types. //! //! [`RngCore`] is the core trait implemented by algorithmic pseudo-random number //! generators and external random-number sources. -//! +//! //! [`SeedableRng`] is an extension trait for construction from fixed seeds and //! other random number generators. -//! +//! //! [`Error`] is provided for error-handling. It is safe to use in `no_std` //! environments. -//! +//! //! The [`impls`] and [`le`] sub-modules include a few small functions to assist //! implementation of [`RngCore`]. -//! +//! //! [`rand`]: https://docs.rs/rand #![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png", @@ -60,34 +60,34 @@ pub mod le; /// The core of a random number generator. -/// +/// /// This trait encapsulates the low-level functionality common to all /// generators, and is the "back end", to be implemented by generators. -/// End users should normally use `Rng` trait from the [`rand`] crate, +/// End users should normally use the `Rng` trait from the [`rand`] crate, /// which is automatically implemented for every type implementing `RngCore`. -/// +/// /// Three different methods for generating random data are provided since the /// optimal implementation of each is dependent on the type of generator. There /// is no required relationship between the output of each; e.g. many /// implementations of [`fill_bytes`] consume a whole number of `u32` or `u64` /// values and drop any remaining unused bytes. -/// +/// /// The [`try_fill_bytes`] method is a variant of [`fill_bytes`] allowing error /// handling; it is not deemed sufficiently useful to add equivalents for /// [`next_u32`] or [`next_u64`] since the latter methods are almost always used /// with algorithmic generators (PRNGs), which are normally infallible. -/// +/// /// Algorithmic generators implementing [`SeedableRng`] should normally have /// *portable, reproducible* output, i.e. fix Endianness when converting values /// to avoid platform differences, and avoid making any changes which affect /// 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. -/// +/// /// It is recommended that implementations also implement: -/// +/// /// - `Debug` with a custom implementation which *does not* print any internal /// state (at least, [`CryptoRng`]s should not risk leaking state through /// `Debug`). @@ -99,37 +99,37 @@ pub mod le; /// implement [`SeedableRng`], to guide users towards proper seeding. /// External / hardware RNGs can choose to implement `Default`. /// - `Eq` and `PartialEq` could be implemented, but are probably not useful. -/// +/// /// # Example -/// +/// /// A simple example, obviously not generating very *random* output: -/// +/// /// ``` /// #![allow(dead_code)] /// use rand_core::{RngCore, Error, impls}; -/// +/// /// struct CountingRng(u64); -/// +/// /// impl RngCore for CountingRng { /// fn next_u32(&mut self) -> u32 { /// self.next_u64() as u32 /// } -/// +/// /// fn next_u64(&mut self) -> u64 { /// self.0 += 1; /// self.0 /// } -/// +/// /// fn fill_bytes(&mut self, dest: &mut [u8]) { /// impls::fill_bytes_via_next(self, dest) /// } -/// +/// /// fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> { /// Ok(self.fill_bytes(dest)) /// } /// } /// ``` -/// +/// /// [`rand`]: https://docs.rs/rand /// [`try_fill_bytes`]: RngCore::try_fill_bytes /// [`fill_bytes`]: RngCore::fill_bytes @@ -148,7 +148,7 @@ 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 - /// via [`next_u32`][impls::next_u64_via_u32] or via + /// via [`next_u32`][impls::next_u64_via_u32] or via /// [`fill_bytes`][impls::next_u64_via_fill]. fn next_u64(&mut self) -> u64; @@ -161,7 +161,7 @@ pub trait RngCore { /// 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). - /// + /// /// This method should guarantee that `dest` is entirely filled /// with new data, and may panic if this is impossible /// (e.g. reading past the end of a file that is being used as the @@ -174,37 +174,37 @@ pub trait RngCore { /// generating random data thus making this the primary method implemented /// by external (true) RNGs (e.g. `OsRng`) which can fail. It may be used /// directly to generate keys and to seed (infallible) PRNGs. - /// + /// /// Other than error handling, this method is identical to [`fill_bytes`]; /// thus this may be implemented using `Ok(self.fill_bytes(dest))` or /// `fill_bytes` may be implemented with /// `self.try_fill_bytes(dest).unwrap()` or more specific error handling. - /// + /// /// [`fill_bytes`]: RngCore::fill_bytes fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>; } /// A marker trait used to indicate that an [`RngCore`] or [`BlockRngCore`] /// implementation is supposed to be cryptographically secure. -/// +/// /// *Cryptographically secure generators*, also known as *CSPRNGs*, should /// satisfy an additional properties over other generators: given the first /// *k* bits of an algorithm's output /// sequence, it should not be possible using polynomial-time algorithms to /// predict the next bit with probability significantly greater than 50%. -/// +/// /// Some generators may satisfy an additional property, however this is not /// required by this trait: if the CSPRNG's state is revealed, it should not be /// computationally-feasible to reconstruct output prior to this. Some other /// generators allow backwards-computation and are consided *reversible*. -/// +/// /// Note that this trait is provided for guidance only and cannot guarantee /// suitability for cryptographic applications. In general it should only be /// implemented for well-reviewed code implementing well-regarded algorithms. -/// +/// /// Note also that use of a `CryptoRng` does not protect against other /// weaknesses such as seeding from a weak entropy source or leaking state. -/// +/// /// [`BlockRngCore`]: block::BlockRngCore pub trait CryptoRng {} @@ -212,11 +212,11 @@ pub trait CryptoRng {} /// /// This trait encapsulates the low-level functionality common to all /// pseudo-random number generators (PRNGs, or algorithmic generators). -/// -/// The `FromEntropy` trait from [`rand`] crate is automatically +/// +/// The `FromEntropy` trait from the [`rand`] crate is automatically /// implemented for every type implementing `SeedableRng`, providing /// a convenient `from_entropy()` constructor. -/// +/// /// [`rand`]: https://docs.rs/rand pub trait SeedableRng: Sized { /// Seed type, which is restricted to types mutably-dereferencable as `u8` @@ -288,17 +288,17 @@ pub trait SeedableRng: Sized { /// for example `0xBAD5EEDu32` or `0x0DDB1A5E5BAD5EEDu64` ("odd biases? bad /// seed"). This is assuming only a small number of values must be rejected. fn from_seed(seed: Self::Seed) -> Self; - + /// Create a new PRNG using a `u64` seed. - /// + /// /// This is a convenience-wrapper around `from_seed` to allow construction /// of any `SeedableRng` from a simple `u64` value. It is designed such that /// low Hamming Weight numbers like 0 and 1 can be used and should still /// result in good, independent seeds to the PRNG which is returned. - /// + /// /// This **is not suitable for cryptography**, as should be clear given that /// the input size is only 64 bits. - /// + /// /// Implementations for PRNGs *may* provide their own implementations of /// this function, but the default implementation should be good enough for /// all purposes. *Changing* the implementation of this function should be @@ -307,33 +307,33 @@ pub trait SeedableRng: Sized { // We use PCG32 to generate a u32 sequence, and copy to the seed const MUL: u64 = 6364136223846793005; const INC: u64 = 11634580027462260723; - + let mut seed = Self::Seed::default(); for chunk in seed.as_mut().chunks_mut(4) { // We advance the state first (to get away from the input value, // in case it has low Hamming Weight). state = state.wrapping_mul(MUL).wrapping_add(INC); - + // Use PCG output function with to_le to generate x: let xorshifted = (((state >> 18) ^ state) >> 27) as u32; let rot = (state >> 59) as u32; let x = xorshifted.rotate_right(rot).to_le(); - + unsafe { let p = &x as *const u32 as *const u8; copy_nonoverlapping(p, chunk.as_mut_ptr(), chunk.len()); } } - + Self::from_seed(seed) } - + /// Create a new PRNG seeded from another `Rng`. /// /// This is the recommended way to initialize PRNGs with fresh entropy. The - /// `FromEntropy` trait from [`rand`] crate provides a convenient + /// `FromEntropy` trait from the [`rand`] crate provides a convenient /// `from_entropy` method based on `from_rng`. - /// + /// /// Usage of this method is not recommended when reproducibility is required /// since implementing PRNGs are not required to fix Endianness and are /// allowed to modify implementations in new releases. @@ -346,7 +346,7 @@ pub trait SeedableRng: Sized { /// between them. /// /// Prefer to seed from a strong external entropy source like `OsRng` from - /// [`rand_os`] crate or from a cryptographic PRNG; if creating a new + /// the [`rand_os`] crate or from a cryptographic PRNG; if creating a new /// generator for cryptographic uses you *must* seed from a strong source. /// /// Seeding a small PRNG from another small PRNG is possible, but @@ -357,7 +357,7 @@ 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. - /// + /// /// [`rand`]: https://docs.rs/rand /// [`rand_os`]: https://docs.rs/rand_os fn from_rng(mut rng: R) -> Result { @@ -436,7 +436,7 @@ impl CryptoRng for Box {} #[cfg(test)] mod test { use super::*; - + #[test] fn test_seed_from_u64() { struct SeedableNum(u64); @@ -448,7 +448,7 @@ mod test { SeedableNum(x[0]) } } - + const N: usize = 8; const SEEDS: [u64; N] = [0u64, 1, 2, 3, 4, 8, 16, -1i64 as u64]; let mut results = [0u64; N]; @@ -456,21 +456,21 @@ mod test { let SeedableNum(x) = SeedableNum::seed_from_u64(*seed); results[i] = x; } - + for (i1, r1) in results.iter().enumerate() { let weight = r1.count_ones(); // This is the binomial distribution B(64, 0.5), so chance of // weight < 20 is binocdf(19, 64, 0.5) = 7.8e-4, and same for // weight > 44. assert!(weight >= 20 && weight <= 44); - + for (i2, r2) in results.iter().enumerate() { if i1 == i2 { continue; } let diff_weight = (r1 ^ r2).count_ones(); assert!(diff_weight >= 20); } } - + // value-breakage test: assert_eq!(results[0], 5029875928683246316); } diff --git a/rand_isaac/src/isaac64.rs b/rand_isaac/src/isaac64.rs index c1dcda63416..b5db351d2ea 100644 --- a/rand_isaac/src/isaac64.rs +++ b/rand_isaac/src/isaac64.rs @@ -40,8 +40,8 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN; /// In spite of being designed with cryptographic security in mind, ISAAC hasn't /// been stringently cryptanalyzed and thus cryptographers do not not /// consensually trust it to be secure. When looking for a secure RNG, prefer -/// `Hc128Rng` from [`rand_hc`] crate instead, which, like ISAAC, is an -/// array-based RNG and one of the stream-ciphers selected the by eSTREAM +/// `Hc128Rng` from the [`rand_hc`] crate instead, which, like ISAAC, is an +/// array-based RNG and one of the stream-ciphers selected the by eSTREAM /// /// ## Overview of the ISAAC-64 algorithm: /// (in pseudo-code) @@ -157,7 +157,7 @@ impl BlockRngCore for Isaac64Core { /// of the algorithm in the `Isaac64Rng` documentation. /// /// Optimisations used (similar to the reference implementation): - /// + /// /// - The loop is unrolled 4 times, once for every constant of mix(). /// - The contents of the main loop are moved to a function `rngstep`, to /// reduce code duplication. @@ -294,7 +294,7 @@ impl SeedableRng for Isaac64Core { } Self::init(seed_extended, 2) } - + fn seed_from_u64(seed: u64) -> Self { let mut key = [w(0); RAND_SIZE]; key[0] = w(seed); diff --git a/src/distributions/weighted.rs b/src/distributions/weighted.rs index 9b83aa91655..d7499596e39 100644 --- a/src/distributions/weighted.rs +++ b/src/distributions/weighted.rs @@ -40,7 +40,7 @@ use core::fmt; /// `N` is the number of weights. /// /// Sampling from `WeightedIndex` will result in a single call to -/// `Uniform::sample` (method of [`Distribution`] trait), which typically +/// `Uniform::sample` (method of the [`Distribution`] trait), which typically /// will request a single value from the underlying [`RngCore`], though the /// exact number depends on the implementaiton of `Uniform::sample`. /// diff --git a/src/rngs/jitter.rs b/src/rngs/jitter.rs index fa6701ec754..9c75f6c1c1d 100644 --- a/src/rngs/jitter.rs +++ b/src/rngs/jitter.rs @@ -599,7 +599,7 @@ impl JitterRng { self.stir_pool(); self.data } - + /// Basic quality tests on the timer, by measuring CPU timing jitter a few /// hundred times. /// @@ -755,7 +755,7 @@ impl JitterRng { /// of entropy one round of the entropy collector can collect in the worst /// case. /// - /// See this crate README on how to use `timer_stats` to test the quality + /// See this crate's README on how to use `timer_stats` to test the quality /// of `JitterRng`. pub fn timer_stats(&mut self, var_rounds: bool) -> i64 { let mut mem = [0; MEMORY_SIZE]; From b72b6aee10a88c20745b955cfcfa370491581506 Mon Sep 17 00:00:00 2001 From: newpavlov Date: Mon, 14 Jan 2019 14:46:57 +0300 Subject: [PATCH 3/3] fix errors --- rand_isaac/src/isaac.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/rand_isaac/src/isaac.rs b/rand_isaac/src/isaac.rs index 7e35ac30ca5..6b596053853 100644 --- a/rand_isaac/src/isaac.rs +++ b/rand_isaac/src/isaac.rs @@ -34,8 +34,8 @@ const RAND_SIZE: usize = 1 << RAND_SIZE_LEN; /// In spite of being designed with cryptographic security in mind, ISAAC hasn't /// been stringently cryptanalyzed and thus cryptographers do not not /// consensually trust it to be secure. When looking for a secure RNG, prefer -/// `Hc128Rng` from [`rand_hc`] crate instead, which, like ISAAC, is an -/// array-based RNG and one of the stream-ciphers selected the by eSTREAM +/// `Hc128Rng` from the [`rand_hc`] crate instead, which, like ISAAC, is an +/// array-based RNG and one of the stream-ciphers selected the by eSTREAM /// /// In 2006 an improvement to ISAAC was suggested by Jean-Philippe Aumasson, /// named ISAAC+[^3]. But because the specification is not complete, because @@ -117,7 +117,7 @@ impl SeedableRng for IsaacRng { fn from_seed(seed: Self::Seed) -> Self { IsaacRng(BlockRng::::from_seed(seed)) } - + /// Create an ISAAC random number generator using an `u64` as seed. /// If `seed == 0` this will produce the same stream of random numbers as /// the reference implementation when used unseeded. @@ -166,7 +166,7 @@ impl BlockRngCore for IsaacCore { /// of the algorithm in the `IsaacRng` documentation. /// /// Optimisations used (similar to the reference implementation): - /// + /// /// - The loop is unrolled 4 times, once for every constant of mix(). /// - The contents of the main loop are moved to a function `rngstep`, to /// reduce code duplication. @@ -320,7 +320,7 @@ impl SeedableRng for IsaacCore { } Self::init(seed_extended, 2) } - + /// Create an ISAAC random number generator using an `u64` as seed. /// If `seed == 0` this will produce the same stream of random numbers as /// the reference implementation when used unseeded.