Merge pull request #1100 from rust-random/rand_distr-features-doc

Correctly document `rand_distr` features and forward "std" feature to `num-traits`
rust-random · Apr 8, 2021 · 2582115 · 2582115
2 parents 35be169 + 52f9a8f
commit 2582115
Show file tree

Hide file tree

Showing 17 changed files with 36 additions and 3 deletions.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -91,7 +91,10 @@ jobs:
           cargo test --target ${{ matrix.target }} --manifest-path rand_core/Cargo.toml --no-default-features
           cargo test --target ${{ matrix.target }} --manifest-path rand_core/Cargo.toml --no-default-features --features=alloc,getrandom
       - name: Test rand_distr
-        run: cargo test --target ${{ matrix.target }} --manifest-path rand_distr/Cargo.toml
+        run: |
+          cargo test --target ${{ matrix.target }} --manifest-path rand_distr/Cargo.toml
+          cargo test --target ${{ matrix.target }} --manifest-path rand_distr/Cargo.toml --no-default-features
+          cargo test --target ${{ matrix.target }} --manifest-path rand_distr/Cargo.toml --no-default-features --features=std,std_math
       - name: Test rand_pcg
         run: cargo test --target ${{ matrix.target }} --manifest-path rand_pcg/Cargo.toml --features=serde1
       - name: Test rand_chacha

diff --git a/rand_distr/Cargo.toml b/rand_distr/Cargo.toml
@@ -11,7 +11,7 @@ description = """
 Sampling from random number distributions
 """
 keywords = ["random", "rng", "distribution", "probability"]
-categories = ["algorithms"]
+categories = ["algorithms", "no-std"]
 edition = "2018"
 include = ["src/", "LICENSE-*", "README.md", "CHANGELOG.md", "COPYRIGHT"]
 
@@ -23,6 +23,7 @@ num-traits = { version = "0.2", default-features = false, features = ["libm"] }
 default = ["std"]
 std = ["alloc", "rand/std"]
 alloc = ["rand/alloc"]
+std_math = ["num-traits/std"]
 
 [dev-dependencies]
 rand_pcg = { version = "0.3.0", path = "../rand_pcg" }

diff --git a/rand_distr/README.md b/rand_distr/README.md
@@ -20,7 +20,17 @@ It is worth mentioning the [statrs] crate which provides similar functionality
 along with various support functions, including PDF and CDF computation. In
 contrast, this `rand_distr` crate focuses on sampling from distributions.
 
-Unlike most Rand crates, `rand_distr` does not currently support `no_std`.
+If the `std` default feature is enabled, `rand_distr` implements the `Error`
+trait for its error types.
+
+The default `alloc` feature (which is implied by the `std` feature) is required
+for some distributions (in particular, `Dirichlet` and `WeightedAliasIndex`).
+
+The floating point functions from `num_traits` and `libm` are used to support
+`no_std` environments and ensure reproducibility. If the floating point
+functions from `std` are prefered, which may provide better accuracy and
+performance but may produce different random values, the `std_math` feature
+can be enabled.
 
 Links:
 

diff --git a/rand_distr/src/binomial.rs b/rand_distr/src/binomial.rs
@@ -55,6 +55,7 @@ impl fmt::Display for Error {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for Error {}
 
 impl Binomial {

diff --git a/rand_distr/src/cauchy.rs b/rand_distr/src/cauchy.rs
@@ -55,6 +55,7 @@ impl fmt::Display for Error {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for Error {}
 
 impl<F> Cauchy<F>

diff --git a/rand_distr/src/dirichlet.rs b/rand_distr/src/dirichlet.rs
@@ -68,6 +68,7 @@ impl fmt::Display for Error {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for Error {}
 
 impl<F> Dirichlet<F>

diff --git a/rand_distr/src/exponential.rs b/rand_distr/src/exponential.rs
@@ -114,6 +114,7 @@ impl fmt::Display for Error {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for Error {}
 
 impl<F: Float> Exp<F>

diff --git a/rand_distr/src/gamma.rs b/rand_distr/src/gamma.rs
@@ -81,6 +81,7 @@ impl fmt::Display for Error {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for Error {}
 
 #[derive(Clone, Copy, Debug)]
@@ -298,6 +299,7 @@ impl fmt::Display for ChiSquaredError {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for ChiSquaredError {}
 
 #[derive(Clone, Copy, Debug)]
@@ -404,6 +406,7 @@ impl fmt::Display for FisherFError {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for FisherFError {}
 
 impl<F> FisherF<F>
@@ -567,6 +570,7 @@ impl fmt::Display for BetaError {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for BetaError {}
 
 impl<F> Beta<F>

diff --git a/rand_distr/src/geometric.rs b/rand_distr/src/geometric.rs
@@ -49,6 +49,7 @@ impl fmt::Display for Error {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for Error {}
 
 impl Geometric {

diff --git a/rand_distr/src/lib.rs b/rand_distr/src/lib.rs
@@ -94,6 +94,7 @@ pub use rand::distributions::{
 pub use self::binomial::{Binomial, Error as BinomialError};
 pub use self::cauchy::{Cauchy, Error as CauchyError};
 #[cfg(feature = "alloc")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))]
 pub use self::dirichlet::{Dirichlet, Error as DirichletError};
 pub use self::exponential::{Error as ExpError, Exp, Exp1};
 pub use self::gamma::{
@@ -118,6 +119,7 @@ pub use self::weibull::{Error as WeibullError, Weibull};
 #[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))]
 pub use rand::distributions::{WeightedError, WeightedIndex};
 #[cfg(feature = "alloc")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))]
 pub use weighted_alias::WeightedAliasIndex;
 
 pub use num_traits;

diff --git a/rand_distr/src/normal.rs b/rand_distr/src/normal.rs
@@ -138,6 +138,7 @@ impl fmt::Display for Error {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for Error {}
 
 impl<F> Normal<F>

diff --git a/rand_distr/src/pareto.rs b/rand_distr/src/pareto.rs
@@ -50,6 +50,7 @@ impl fmt::Display for Error {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for Error {}
 
 impl<F> Pareto<F>

diff --git a/rand_distr/src/pert.rs b/rand_distr/src/pert.rs
@@ -65,6 +65,7 @@ impl fmt::Display for PertError {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for PertError {}
 
 impl<F> Pert<F>

diff --git a/rand_distr/src/poisson.rs b/rand_distr/src/poisson.rs
@@ -56,6 +56,7 @@ impl fmt::Display for Error {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for Error {}
 
 impl<F> Poisson<F>

diff --git a/rand_distr/src/triangular.rs b/rand_distr/src/triangular.rs
@@ -61,6 +61,7 @@ impl fmt::Display for TriangularError {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for TriangularError {}
 
 impl<F> Triangular<F>

diff --git a/rand_distr/src/weibull.rs b/rand_distr/src/weibull.rs
@@ -50,6 +50,7 @@ impl fmt::Display for Error {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for Error {}
 
 impl<F> Weibull<F>

diff --git a/rand_distr/src/weighted_alias.rs b/rand_distr/src/weighted_alias.rs
@@ -354,13 +354,15 @@ impl_weight_for_float!(f64);
 impl_weight_for_float!(f32);
 impl_weight_for_int!(usize);
 #[cfg(not(target_os = "emscripten"))]
+#[cfg_attr(doc_cfg, doc(cfg(not(target_os = "emscripten"))))]
 impl_weight_for_int!(u128);
 impl_weight_for_int!(u64);
 impl_weight_for_int!(u32);
 impl_weight_for_int!(u16);
 impl_weight_for_int!(u8);
 impl_weight_for_int!(isize);
 #[cfg(not(target_os = "emscripten"))]
+#[cfg_attr(doc_cfg, doc(cfg(not(target_os = "emscripten"))))]
 impl_weight_for_int!(i128);
 impl_weight_for_int!(i64);
 impl_weight_for_int!(i32);