Update documentation

rand_distr/src/cauchy.rs

@@ -17,7 +17,7 @@ use rand::Rng;
 /// The Cauchy distribution `Cauchy(median, scale)`.
 ///
 /// The Cauchy distribution is a continuous probability distribution with
-/// parameters `median` and `scale`.
+/// parameters `median` (`x₀`) and `scale` (`γ`).
 ///
 /// This distribution has a density function:
 /// `f(x) = 1 / (pi * scale * (1 + ((x - median) / scale)^2))`
@@ -27,9 +27,9 @@ use rand::Rng;
 ///
 /// # Plot
 ///
-/// The plot illustrates the Cauchy distribution with various parameters.
-/// Note how the `median` parameter `x₀` shifts the distribution along the x-axis,
-/// and the `scale` parameter `γ` changes the density around the median.
+/// The plot illustrates the Cauchy distribution with various values of `x₀` and `γ`.
+/// Note how the median parameter `x₀` shifts the distribution along the x-axis, 
+/// and how the scale `γ` changes the density around the median.
 /// 
 /// The standard Cauchy distribution is the special case with `median = 0` and `scale = 1`.
 ///

rand_distr/src/dirichlet.rs

@@ -193,7 +193,7 @@ where
 /// 
 /// # Plot
 /// 
-/// The following plot illustrates the Dirichlet distribution with various parameters.
+/// The following plot illustrates the Dirichlet distribution with various `alpha`s.
 /// 
 /// ![Dirichlet distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/dirichlet.png)
 ///

rand_distr/src/exponential.rs

@@ -19,18 +19,18 @@ use rand::Rng;
 /// with rate parameter `λ = 1`. This is equivalent to `Exp::new(1.0)` or
 /// sampling with `-rng.gen::<f64>().ln()`, but faster.
 ///
-/// See `Exp` for the general exponential distribution.
+/// See [`Exp`](crate::Exp) for the general exponential distribution.
+///
+/// Implemented via the ZIGNOR variant[^1] of the Ziggurat method. The exact
+/// description in the paper was adjusted to use tables for the exponential
+/// distribution rather than normal.
 ///
 /// # Plot
 ///
 /// The following plot illustrates the exponential distribution with `λ = 1`.
 ///
 /// ![Exponential distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/exponential_exp1.svg)
 ///
-/// Implemented via the ZIGNOR variant[^1] of the Ziggurat method. The exact
-/// description in the paper was adjusted to use tables for the exponential
-/// distribution rather than normal.
-///
 /// [^1]: Jurgen A. Doornik (2005). [*An Improved Ziggurat Method to
 ///       Generate Normal Random Samples*](
 ///       https://www.doornik.com/research/ziggurat.pdf).
@@ -83,16 +83,17 @@ impl Distribution<f64> for Exp1 {
 
 /// The exponential distribution `Exp(lambda)`.
 ///
-/// This distribution has density function: `f(x) = lambda * exp(-lambda * x)`
-/// for `x > 0`, when `lambda > 0`. For `lambda = 0`, all samples yield infinity.
+/// This distribution has density function: `f(x) = λ * exp(-λ * x)`
+/// for `x > 0`, when `λ > 0`. For `λ = 0`, all samples yield infinity.
 ///
-/// Note that [`Exp1`](crate::Exp1) is an optimised implementation for `lambda = 1`.
+/// Note that [`Exp1`](crate::Exp1) is an optimised implementation for `λ = 1`.
 ///
 /// # Plot
 ///
 /// The following plot illustrates the exponential distribution with 
-/// various values of `lambda`.
-/// The `lambda` parameter controls the rate of decay as `x` approaches infinity.
+/// various values of `λ`.
+/// The `λ` parameter controls the rate of decay as `x` approaches infinity,
+/// and the mean of the distribution is `1/λ`.
 ///
 /// ![Exponential distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/exponential.svg)
 ///

rand_distr/src/frechet.rs

@@ -22,11 +22,10 @@ use rand::Rng;
 ///
 /// # Plot
 ///
-/// The plot shows the Fréchet distribution with various parameters.
+/// The plot shows the Fréchet distribution with various values of `μ`, `σ`, and `α`.
 /// Note how the location parameter `μ` shifts the distribution along the x-axis,
 /// the scale parameter `σ` stretches or compresses the distribution along the x-axis,
-/// and the shape parameter `α` changes the severity of the increase in density
-/// towards the lower bound.
+/// and the shape parameter `α` changes the tail behavior.
 ///
 /// ![Fréchet distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/frechet.svg)
 ///

rand_distr/src/gamma.rs

@@ -35,18 +35,20 @@ use serde::{Deserialize, Serialize};
 /// where `Γ` is the Gamma function, `k` is the shape and `θ` is the
 /// scale and both `k` and `θ` are strictly positive.
 ///
+/// The algorithm used is that described by Marsaglia & Tsang 2000[^1],
+/// falling back to directly sampling from an Exponential for `shape
+/// == 1`, and using the boosting technique described in that paper for
+/// `shape < 1`.
+///
 /// # Plot
 ///
 /// The following plot illustrates the Gamma distribution with
-/// various parameters.
+/// various values of `k` and `θ`.
+/// Curves with `θ = 1` are more saturated, while corresponding 
+/// curves with `θ = 2` have a lighter color.
 ///
 /// ![Gamma distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/gamma.svg)
 ///
-/// The algorithm used is that described by Marsaglia & Tsang 2000[^1],
-/// falling back to directly sampling from an Exponential for `shape
-/// == 1`, and using the boosting technique described in that paper for
-/// `shape < 1`.
-///
 /// # Example
 ///
 /// ```

rand_distr/src/geometric.rs

@@ -21,7 +21,8 @@ use rand::Rng;
 /// # Plot
 ///
 /// The following plot illustrates the geometric distribution for various values of `p`.
-/// Note how the higher `p` is, the more likely it is to have a success early on.
+/// Note how higher `p` values shift the distribution to the left, and the mean
+/// of the distribution is `1/p`.
 ///
 /// ![Geometric distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/geometric.svg)
 ///

rand_distr/src/gumbel.rs

@@ -23,7 +23,7 @@ use rand::Rng;
 ///
 /// # Plot
 ///
-/// The following plot illustrates the Gumbel distribution with various parameters.
+/// The following plot illustrates the Gumbel distribution with various values of `μ` and `σ`.
 /// Note how the location parameter `μ` shifts the distribution along the x-axis,
 /// and the scale parameter `σ` changes the density around `μ`.
 /// Note also the asymptotic behavior of the distribution towards the right.

rand_distr/src/inverse_gaussian.rs

@@ -24,15 +24,15 @@ impl fmt::Display for Error {
 #[cfg(feature = "std")]
 impl std::error::Error for Error {}
 
-/// The [inverse Gaussian distribution](https://en.wikipedia.org/wiki/Inverse_Gaussian_distribution)
+/// The [inverse Gaussian distribution](https://en.wikipedia.org/wiki/Inverse_Gaussian_distribution) `IG(μ, λ)`
 /// 
-/// This is a continuous probability distribution with two parameters, `mean` and `shape`,
+/// This is a continuous probability distribution with two parameters, `mean` (`μ`) and `shape` (`λ`),
 /// defined for `x > 0`.
 /// It is also known as the Wald distribution.
 /// 
 /// # Plot
 /// 
-/// The following plot shows the inverse Gaussian distribution with various parameters.
+/// The following plot shows the inverse Gaussian distribution with various values of `μ` and `λ`.
 /// 
 /// ![Inverse Gaussian distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/inverse_gaussian.svg)
 /// 

rand_distr/src/normal.rs

@@ -27,7 +27,7 @@ use rand::Rng;
 ///
 /// The following diagram shows the standard normal distribution.
 ///
-/// ![Standard normal distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/normal.svg)
+/// ![Standard normal distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/standard_normal.svg)
 ///
 /// # Example
 /// ```
@@ -108,8 +108,9 @@ impl Distribution<f64> for StandardNormal {
 ///
 /// # Plot
 ///
-/// The following diagram shows the normal distribution with various parameters.
-/// [`StandardNormal`] is illustrated with `μ = 0` and `σ = 1`.
+/// The following diagram shows the normal distribution with various values of `μ`
+/// and `σ`.
+/// The blue curve is the [`StandardNormal`] distribution, `N(0, 1)`.
 ///
 /// ![Normal distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/normal.svg)
 ///
@@ -231,6 +232,13 @@ where
 ///
 /// If `X` is log-normal distributed, then `ln(X)` is `N(mean, std_dev**2)`
 /// distributed.
+/// 
+/// # Plot
+/// 
+/// The following diagram shows the log-normal distribution with various values
+/// of `μ` and `σ`.
+/// 
+/// ![Log-normal distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/log_normal.svg)
 ///
 /// # Example
 ///

rand_distr/src/normal_inverse_gaussian.rs

@@ -28,15 +28,15 @@ impl fmt::Display for Error {
 #[cfg(feature = "std")]
 impl std::error::Error for Error {}
 
-/// The [normal-inverse Gaussian distribution](https://en.wikipedia.org/wiki/Normal-inverse_Gaussian_distribution)
-///
+/// The [normal-inverse Gaussian distribution](https://en.wikipedia.org/wiki/Normal-inverse_Gaussian_distribution) `NIG(α, β)`
+/// 
 /// This is a continuous probability distribution with two parameters, `alpha` and `beta`,
-/// defined for `(-∞, ∞)`.
-/// It is also known as the normal-Wald distribution.
+/// defined in `(-∞, ∞)`.
+/// It is also known as the `normal-Wald` distribution.
 /// 
 /// # Plot
 /// 
-/// The following plot shows the normal-inverse Gaussian distribution with various parameters.
+/// The following plot shows the normal-inverse Gaussian distribution with various values of `α` and `β`.
 /// 
 /// ![Normal-inverse Gaussian distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/normal_inverse_gaussian.svg)
 /// 

rand_distr/src/pareto.rs

@@ -13,12 +13,17 @@ use core::fmt;
 use num_traits::Float;
 use rand::Rng;
 
+/// The Pareto distribution `Pareto(scale, shape)`.
+/// 
 /// The Pareto distribution is a continuous probability distribution with
-/// parameters `scale` (α) and `shape` (x<sub>m</sub> or k).
+/// parameters `scale` (`α`) and `shape` (`x`<sub>`m`</sub> or `k`).
 ///
 /// # Plot
 ///
-/// The following plot shows the Pareto distribution with various parameters.
+/// The following plot shows the Pareto distribution with various values of 
+/// `scale` and `shape`.
+/// Note how the scale parameter `α` corresponds to the height of the jump
+/// in density at `x = x`<sub>`m`</sub>, and to the rate of decay in the tail.
 ///
 /// ![Pareto distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/pareto.svg)
 ///

rand_distr/src/pert.rs

@@ -12,16 +12,18 @@ use core::fmt;
 use num_traits::Float;
 use rand::Rng;
 
-/// The PERT distribution.
+/// The PERT distribution `PERT(min, max, mode, shape)`.
 ///
 /// Similar to the [`Triangular`] distribution, the PERT distribution is
 /// parameterised by a range and a mode within that range. Unlike the
 /// [`Triangular`] distribution, the probability density function of the PERT
 /// distribution is smooth, with a configurable weighting around the mode.
+/// If left unspecified, the default value of `shape` is `4.0`.
 ///
 /// # Plot
 ///
-/// The following plot shows the PERT distribution with various parameters.
+/// The following plot shows the PERT distribution with various values of
+/// `min`, `max`, `mode`, and `shape`.
 ///
 /// ![PERT distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/pert.svg)
 ///

rand_distr/src/poisson.rs

@@ -15,13 +15,18 @@ use num_traits::{Float, FloatConst};
 use rand::Rng;
 
 /// The Poisson distribution `Poisson(lambda)`.
+/// 
+/// The Poisson distribution is a discrete probability distribution with
+/// rate parameter `λ`. It models the number of events occurring in a fixed
+/// interval of time or space.
 ///
 /// This distribution has a density function:
-/// `f(k) = lambda^k * exp(-lambda) / k!` for `k >= 0`.
+/// `f(k) = λ^k * exp(-λ) / k!` for `k >= 0`.
 ///
 /// # Plot
 ///
-/// The following plot shows the Poisson distribution with various values of `lambda`.
+/// The following plot shows the Poisson distribution with various values of `λ`.
+/// Note how a higher `λ` results in more expected events per unit interval.
 ///
 /// ![Poisson distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/poisson.svg)
 ///

rand_distr/src/skew_normal.rs

@@ -16,15 +16,21 @@ use rand::Rng;
 /// The [skew normal distribution] `SN(location, scale, shape)`.
 ///
 /// The skew normal distribution is a generalization of the
-/// [`Normal`] distribution to allow for non-zero skewness.
+/// [`Normal`](crate::Normal) distribution to allow for non-zero skewness.
+/// 
+/// The `location` and `scale` parameters correspond to the 
+/// mean and standard deviation of the normal distribution,
+/// respectively. The `shape` parameter controls the skewness.
 ///
 /// It has the density function, for `scale > 0`,
 /// `f(x) = 2 / scale * phi((x - location) / scale) * Phi(alpha * (x - location) / scale)`
 /// where `phi` and `Phi` are the density and distribution of a standard normal variable.
 ///
 /// # Plot
 ///
-/// The following plot shows the skew normal distribution with various values of `alpha`.
+/// The following plot shows the skew normal distribution with `location = 0`, `scale = 1`
+/// (corresponding to the [`standard normal distribution`](crate::StandardNormal)), and 
+/// various values of `shape`.
 ///
 /// ![Skew normal distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/skew_normal.svg)
 ///

rand_distr/src/triangular.rs

@@ -12,7 +12,7 @@ use core::fmt;
 use num_traits::Float;
 use rand::Rng;
 
-/// The triangular distribution.
+/// The triangular distribution `Triangular(min, max, mode)`.
 ///
 /// A continuous probability distribution parameterised by a range, and a mode
 /// (most likely value) within that range.
@@ -22,7 +22,8 @@ use rand::Rng;
 ///
 /// # Plot
 ///
-/// The following plot shows the triangular distribution with various parameters.
+/// The following plot shows the triangular distribution with various values of
+/// `min`, `max`, and `mode`.
 ///
 /// ![Triangular distribution](https://raw.githubusercontent.com/rust-random/charts/main/charts/triangular.svg)
 ///

rand_distr/src/unit_ball.rs

@@ -10,14 +10,20 @@ use crate::{uniform::SampleUniform, Distribution, Uniform};
 use num_traits::Float;
 use rand::Rng;
 
-/// Samples uniformly from the unit ball (surface and interior) in three
-/// dimensions.
+/// Samples uniformly from the volume of the unit ball in three dimensions.
 ///
 /// Implemented via rejection sampling.
+/// 
+/// For a distribution that samples only from the surface of the unit ball,
+/// see [`UnitSphere`](crate::UnitSphere).
+/// 
+/// For a similar distribution in two dimensions, see [`UnitDisc`](crate::UnitDisc).
 ///
 /// # Plot
 ///
 /// The following plot shows the unit ball in three dimensions.
+/// This distribution samples individual points from the entire volume
+/// of the ball.
 ///
 /// ![Unit ball](https://raw.githubusercontent.com/rust-random/charts/main/charts/unit_ball.svg)
 ///

rand_distr/src/unit_circle.rs

@@ -10,9 +10,14 @@ use crate::{uniform::SampleUniform, Distribution, Uniform};
 use num_traits::Float;
 use rand::Rng;
 
-/// Samples uniformly from the edge of the unit circle in two dimensions.
+/// Samples uniformly from the circumference of the unit circle in two dimensions.
 ///
 /// Implemented via a method by von Neumann[^1].
+/// 
+/// For a distribution that also samples from the interior of the unit circle,
+/// see [`UnitDisc`](crate::UnitDisc).
+/// 
+/// For a similar distribution in three dimensions, see [`UnitSphere`](crate::UnitSphere).
 ///
 /// # Plot
 ///

rand_distr/src/unit_disc.rs

@@ -13,10 +13,16 @@ use rand::Rng;
 /// Samples uniformly from the unit disc in two dimensions.
 ///
 /// Implemented via rejection sampling.
+/// 
+/// For a distribution that samples only from the circumference of the unit disc,
+/// see [`UnitCircle`](crate::UnitCircle).
+/// 
+/// For a similar distribution in three dimensions, see [`UnitBall`](crate::UnitBall).
 ///
 /// # Plot
 ///
 /// The following plot shows the unit disc.
+/// This distribution samples individual points from the entire area of the disc.
 ///
 /// ![Unit disc](https://raw.githubusercontent.com/rust-random/charts/main/charts/unit_disc.svg)
 ///

rand_distr/src/unit_sphere.rs

@@ -13,12 +13,17 @@ use rand::Rng;
 /// Samples uniformly from the surface of the unit sphere in three dimensions.
 ///
 /// Implemented via a method by Marsaglia[^1].
+/// 
+/// For a distribution that also samples from the interior of the sphere,
+/// see [`UnitBall`](crate::UnitBall).
+/// 
+/// For a similar distribution in two dimensions, see [`UnitCircle`](crate::UnitCircle).
 ///
 /// # Plot
 ///
 /// The following plot shows the unit sphere as a wireframe.
-/// The wireframe should only illustrate that this distribution samples
-/// from the surface of the sphere only, not the interior.
+/// The wireframe is meant to illustrate that this distribution samples
+/// from the surface of the sphere only, not from the interior.
 ///
 /// ![Unit sphere](https://raw.githubusercontent.com/rust-random/charts/main/charts/unit_sphere.svg)
 ///