Some polish

Author: pitdicker

src/lib.rs

@@ -13,21 +13,21 @@
 //! To quickly get you started, the easiest and most high-level way to just get
 //! some random value is to use [`random()`].
 //!
-//! ```rust
+//! ```
 //! let x: u8 = rand::random();
 //! println!("{}", x);
 //!
 //! let y = rand::random::<f64>();
 //! println!("{}", y);
 //!
 //! if rand::random() { // generates a boolean
-//!     println!("Better lucky than good!");
+//!     println!("Heads!");
 //! }
 //! ```
 //!
 //! This functionality is however very basic. As soon as you need something
 //! slightly more specific, like a random value in some range, you have to know
-//! a bit more about how things work, which are discussed below.
+//! a bit more about how things work, which will be discussed below.
 //!
 //! ## Examples
 //!
@@ -45,19 +45,21 @@
 //!
 //! - a random number generator (RNG);
 //! - some function to transform the 'bag of bits' from the RNG to a value you
-//!   can use.
+//!   can use (which we call a distribution, although we use the term for a bit
+//!   more functionality than what fits the meaning).
 //!
 //! There are many kinds of RNGs, with different trade-offs. Rand comes with a
-//! default, [`thread_rng`]. The numbers it generates are suitable to use in all
-//! situations.
+//! good all-use default, [`thread_rng`]. It is reasonably fast and has good
+//! quality (secure and without patterns).
 //!
 //! To turn the output of the RNG into something usable, you usually want to use
 //! the methods from the [`Rng`] trait:
 //!
-//! - [`gen`] generates a random value that fits the type.
-//!   For example `let val: u16 = rng.gen()` will just fill an `u16` with 16
-//!   random bits. But for floats the value will be generated between 0 and 1;
-//!   which is more usable than any value between 0 and infinity.
+//! - [`gen`] generates a random value appropriate for the type.
+//!   For example `let val: u16 = rng.gen()` will produces a random value
+//!   between 0 and `std::u16::MAX`. But for floats the value will be generated
+//!   uniformly between 0 and 1, which is more useful than a completely random
+//!   float value (including NaN and infinity);
 //! - [`gen_range`] samples from a specific range of values;
 //! - [`sample`], for all situations where you need something slightly more
 //!   complex.
@@ -66,7 +68,7 @@
 //!
 //! ### Examples
 //!
-//! ```rust
+//! ```
 //! // Rng is the main trait and needs to be imported:
 //! use rand::{Rng, thread_rng};
 //!
@@ -88,30 +90,38 @@
 //! impossible, but hard and slow. Generally the operating systems collects some
 //! of them, by measuring different kinds of noice/jitter in the hardware.
 //!
-//! What is always used instead is a psuedo-random number generator. This is a
-//! clever algorithm that can produce an infinite stream of random numbers from
-//! a small seed. There exist algorithms that produce random numbers that are in
-//! no measurable way any less random than pulling values 'out of thin air'.
+//! What is always used instead is a psuedo-random number generator (PRNG). This
+//! is a clever algorithm that can produce an infinite stream of psuedo-random
+//! numbers from a small seed. There exist algorithms that produce random
+//! numbers that are in no practically measurable way any less random than
+//! pulling values 'out of thin air'. Except that the random number stream can
+//! be reproduced if you know the seed.
 //!
 //! There are two very different groups interested in developing PRNGs: one
-//! interested in simulations and statistics, another in cryptography. From both
-//! groups Rand picks one good PRNG algorithm. They are exposed as:
+//! interested in simulations and statistics, another in cryptography (sometimes
+//! PRNGs from the latter are more specifically called a CSPRNG). From both
+//! groups Rand picks one good algorithm. They are exposed as:
 //!
 //! - [`SmallRng`]. Uses little memory, and is very fast.
 //!   Note: The currently picked algorithm is not ideal, but in a future version
 //!   the values will for all practical purposes be statistically indiscernible
 //!   from true randomness.
-//! - [`StdRng`]. In addition to the output being indiscernible from true
-//!   randomness, this PRNG is unpredictable, even if you know the
-//!   implementation. This requirement makes it slower and/or use more memory
-//!   however.
+//! - [`StdRng`]. It is a requirement for a CSPRNG that the output is basically
+//!   indiscernible from true randomness, as otherwise information could be
+//!   leaked. In addition this PRNG is unpredictable, even if you know the
+//!   implementation. This is an important property for any situation where
+//!   there might be an adversary, like cryptography, but certainly not limited
+//!   to that. This requirement makes it slower and/or use more memory however.
 //!
 //! One of the problems with PRNGs is that they need a seed (which is what the
 //! [`SeedableRng`] trait is for). Where do you get such a seed? Two options:
 //!
 //! - Just use a constant. This is good when you need reproducible results, for
 //!   example to procedurally generate a game world). See the
-//!   [`SeedableRng::from_seed`] documentation.
+//!   [`SeedableRng::from_seed`] documentation. You may want to combine this
+//!   with a named PRNG from the [`prng`] module or from other crates, because
+//!   the algorithm of [`StdRng`] and [`SmallRng`] can change per release and/or
+//!   platform.
 //! - Get a random value from somewhere at runtime. The
 //!   [`FromEntropy::from_entropy`] method helps here. It will usually get the
 //!   seed from the operating system's PRNG (using [`EntropyRng`]).
@@ -123,27 +133,26 @@
 //!
 //! [`ThreadRng`] abstracts away most of these issues. It uses [`StdRng`], which
 //! is always a safe choice. Seeding happens automatically on first use. The
-//! PRNG its state is stored in thread local storage, so no need to plumb the
+//! PRNG's state is stored in thread local storage, so no need to plumb the
 //! state through an API. You can easily get a mutable reference to it with the
 //! [`thread_rng`] function.
 //!
 //! ### Conclusion
 //!
 //! - [`thread_rng`] is what you often want to use.
-//! - If you want more control or better performance, use [`StdRng`] or
-//!   [`SmallRng`].
+//! - If you want more control, flexibility, or better performance, use
+//!   [`StdRng`], [`SmallRng`] or choose a specific PRNG algorithm.
 //! - If you do not use [`thread_rng`], use [`FromEntropy::from_entropy`] for
 //!   seeding.
 //! - If you need reproducibility, use [`SeedableRng::from_seed`] combined with
-//!   a named PRNG from the [`prng`] module or other crates (i.e. not
-//!   [`StdRng`]/[`SmallRng`] which may be adjusted in the future.)
+//!   a named PRNG.
 //!
 //! For more information, and notes on cryptographic security, see the
 //! documentation in the [`prng`] module.
 //!
 //! ### Examples
 //!
-//! Examples of seeding PRNGs.
+//! Examples of seeding PRNGs:
 //!
 //! ```
 //! # use rand::{Rng, Error};
@@ -186,7 +195,7 @@
 //! generate floating point values in the (0, 1) interval.
 //!
 //! For floating point values you may want to use probability distributions.
-//! For example time of decay is often modelled with an exponential
+//! For example, time of decay is often modelled with an exponential
 //! distribution [`Exp`], and the log-normal, [`LogNormal`] distribution
 //! provides a good model of many natural phenomona.
 //!
@@ -203,7 +212,7 @@
 //!
 //! Sampling from a distribution:
 //!
-//! ```rust
+//! ```
 //! use rand::{thread_rng, Rng};
 //! use rand::distributions::Exp;
 //!
@@ -214,7 +223,7 @@
 //!
 //! Implementing the [`Standard`] distribution for a user type:
 //!
-//! ```rust
+//! ```
 //! # #![allow(dead_code)]
 //! use rand::Rng;
 //! use rand::distributions::{Distribution, Standard};
@@ -235,9 +244,11 @@
 //!
 //! Rand contains some more functionality not discussed above.
 //!
+//! - [`Rng::fill`] and [`Rng::try_fill`] as fast alternatives to fill a slice
+//!   of integers.
 //! - [`Rng::shuffle`] can be used to shuffle slices.
 //! - [`Rng::choose`] to pick one element at random from a slice, and the
-//!   functions in the [`seq`] the pick multiple.
+//!   functions in the [`seq`] module to the pick multiple.
 //! - [`Rng::sample_iter`] to get an iterator for the choosen distribution.
 //! - [`Rng::gen_bool`] to generate events with weighted probability.
 //! - [`distributions::WeightedChoice`] can be used to pick elements at random
@@ -283,7 +294,7 @@
 //!
 //! ### Example
 //!
-//! ```rust
+//! ```
 //! # use rand::thread_rng;
 //! use rand::Rng;
 //!
@@ -308,6 +319,8 @@
 //! [`Open01`]: distributions/struct.Open01.html
 //! [`OsRng`]: os/struct.OsRng.html
 //! [`Rng::choose`]: trait.Rng.html#method.choose
+//! [`Rng::fill`]: trait.Rng.html#method.fill
+//! [`Rng::try_fill`]: trait.Rng.html#method.try_fill
 //! [`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
@@ -442,7 +455,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// use rand::{thread_rng, Rng};
     ///
     /// let mut rng = thread_rng();
@@ -471,7 +484,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// use rand::{thread_rng, Rng};
     ///
     /// let mut rng = thread_rng();
@@ -488,7 +501,7 @@ pub trait Rng: RngCore {
     ///
     /// ### Example
     ///
-    /// ```rust
+    /// ```
     /// use rand::{thread_rng, Rng};
     /// use rand::distributions::Uniform;
     ///
@@ -503,7 +516,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// use rand::{thread_rng, Rng};
     /// use rand::distributions::{Alphanumeric, Uniform, Standard};
     ///
@@ -545,7 +558,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// use rand::{thread_rng, Rng};
     ///
     /// let mut arr = [0i8; 20];
@@ -574,7 +587,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// # use rand::Error;
     /// use rand::{thread_rng, Rng};
     ///
@@ -601,7 +614,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// use rand::{thread_rng, Rng};
     ///
     /// let mut rng = thread_rng();
@@ -666,7 +679,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// use rand::{thread_rng, Rng};
     ///
     /// let mut rng = thread_rng();
@@ -711,7 +724,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// # #![allow(deprecated)]
     /// use rand::{thread_rng, Rng};
     ///
@@ -734,7 +747,7 @@ pub trait Rng: RngCore {
     ///
     /// # Example
     ///
-    /// ```rust
+    /// ```
     /// # #![allow(deprecated)]
     /// use rand::{thread_rng, Rng};
     ///
@@ -931,7 +944,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};
     ///
@@ -1118,7 +1131,7 @@ pub fn weak_rng() -> XorShiftRng {
 ///
 /// # Example
 ///
-/// ```rust
+/// ```
 /// # #![allow(deprecated)]
 /// use rand::{thread_rng, sample};
 ///

src/thread_rng.rs

@@ -128,7 +128,7 @@ impl CryptoRng for ThreadRng {}
 ///
 /// # Examples
 ///
-/// ```rust
+/// ```
 /// let x = rand::random::<u8>();
 /// println!("{}", x);
 ///
@@ -143,7 +143,7 @@ impl CryptoRng for ThreadRng {}
 /// If you're calling `random()` in a loop, caching the generator as in the
 /// following example can increase performance.
 ///
-/// ```rust
+/// ```
 /// # #![allow(deprecated)]
 /// use rand::Rng;
 ///