Document known issues: #1378, #1312, #1476.

Author: dhardy

CHANGELOG.md

@@ -20,6 +20,7 @@ You may also find the [Upgrade Guide](https://rust-random.github.io/book/update.
 - Fix portability of `rand::distributions::Slice` (#1469)
 - Rename `rand::distributions` to `rand::distr` (#1470)
 - The `serde1` feature has been renamed `serde` (#1477)
+- Mark `WeightError`, `PoissonError`, `BinomialError` as `#[non_exhaustive]` (#1480).
 
 ## [0.9.0-alpha.1] - 2024-03-18
 - Add the `Slice::num_choices` method to the Slice distribution (#1402)

rand_distr/src/binomial.rs

@@ -26,6 +26,10 @@ use rand::Rng;
 ///
 /// `f(k) = n!/(k! (n-k)!) p^k (1-p)^(n-k)` for `k >= 0`.
 ///
+/// # Known issues
+///
+/// See documentation of [`Binomial::new`].
+///
 /// # Plot
 ///
 /// The following plot of the binomial distribution illustrates the
@@ -54,6 +58,8 @@ pub struct Binomial {
 
 /// Error type returned from [`Binomial::new`].
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
+// Marked non_exhaustive to allow a new error code in the solution to #1378.
+#[non_exhaustive]
 pub enum Error {
     /// `p < 0` or `nan`.
     ProbabilityTooSmall,
@@ -76,6 +82,13 @@ impl std::error::Error for Error {}
 impl Binomial {
     /// Construct a new `Binomial` with the given shape parameters `n` (number
     /// of trials) and `p` (probability of success).
+    ///
+    /// # Known issues
+    ///
+    /// Although this method should return an [`Error`] on invalid parameters,
+    /// some (extreme) parameter combinations are known to return a [`Binomial`]
+    /// object which panics when [sampled](Distribution::sample).
+    /// See [#1378](https://github.com/rust-random/rand/issues/1378).
     pub fn new(n: u64, p: f64) -> Result<Binomial, Error> {
         if !(p >= 0.0) {
             return Err(Error::ProbabilityTooSmall);

rand_distr/src/poisson.rs

@@ -23,6 +23,10 @@ use rand::Rng;
 /// This distribution has density function:
 /// `f(k) = λ^k * exp(-λ) / k!` for `k >= 0`.
 ///
+/// # Known issues
+///
+/// See documentation of [`Poisson::new`].
+///
 /// # Plot
 ///
 /// The following plot shows the Poisson distribution with various values of `λ`.
@@ -56,6 +60,8 @@ where
 
 /// Error type returned from [`Poisson::new`].
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
+// Marked non_exhaustive to allow a new error code in the solution to #1312.
+#[non_exhaustive]
 pub enum Error {
     /// `lambda <= 0`
     ShapeTooSmall,
@@ -82,6 +88,15 @@ where
 {
     /// Construct a new `Poisson` with the given shape parameter
     /// `lambda`.
+    ///
+    /// # Known issues
+    ///
+    /// Although this method should return an [`Error`] on invalid parameters,
+    /// some (extreme) values of `lambda` are known to return a [`Poisson`]
+    /// object which hangs when [sampled](Distribution::sample).
+    /// Large (less extreme) values of `lambda` may result in successful
+    /// sampling but with reduced precision.
+    /// See [#1312](https://github.com/rust-random/rand/issues/1312).
     pub fn new(lambda: F) -> Result<Poisson<F>, Error> {
         if !lambda.is_finite() {
             return Err(Error::NonFinite);

src/distr/weighted_index.rs

@@ -704,6 +704,8 @@ mod test {
 
 /// Errors returned by [`WeightedIndex::new`], [`WeightedIndex::update_weights`] and other weighted distributions
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+// Marked non_exhaustive to allow a new error code in the solution to #1476.
+#[non_exhaustive]
 pub enum WeightError {
     /// The input weight sequence is empty, too long, or wrongly ordered
     InvalidInput,

src/seq/slice.rs

@@ -189,6 +189,12 @@ pub trait IndexedRandom: Index<usize> {
     /// if the "nightly" feature is enabled, or `O(length)` space and
     /// `O(length + amount * log length)` time otherwise.
     ///
+    /// # Known issues
+    ///
+    /// The algorithm currently used to implement this method loses accuracy
+    /// when small values are used for weights.
+    /// See [#1476](https://github.com/rust-random/rand/issues/1476).
+    ///
     /// # Example
     ///
     /// ```