From 769bcb6e4c73dce7f57080cc53acc3f9d4c9c60f Mon Sep 17 00:00:00 2001 From: TheIronBorn Date: Mon, 18 Mar 2024 08:42:42 +0000 Subject: [PATCH] Document more crate feature usage (#1411) --- Cargo.toml | 2 +- rand_core/src/lib.rs | 1 + src/distributions/distribution.rs | 1 + src/distributions/float.rs | 27 ++++++++++++++-------- src/distributions/integer.rs | 22 ++++++++++++++---- src/distributions/mod.rs | 1 + src/distributions/other.rs | 5 ++-- src/distributions/slice.rs | 1 + src/distributions/uniform.rs | 38 +++++++++++++++++++------------ src/seq/mod.rs | 13 ++++++----- 10 files changed, 74 insertions(+), 37 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 1d8cfbe057..3e9d4a1173 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -19,7 +19,7 @@ include = ["src/", "LICENSE-*", "README.md", "CHANGELOG.md", "COPYRIGHT"] [package.metadata.docs.rs] # To build locally: -# RUSTDOCFLAGS="--cfg doc_cfg" cargo +nightly doc --all-features --no-deps --generate-link-to-definition --open +# RUSTDOCFLAGS="--cfg doc_cfg -Zunstable-options --generate-link-to-definition" cargo +nightly doc --all --all-features --no-deps --open all-features = true rustdoc-args = ["--cfg", "doc_cfg", "--generate-link-to-definition"] diff --git a/rand_core/src/lib.rs b/rand_core/src/lib.rs index d42ab8d63e..70424e6c9c 100644 --- a/rand_core/src/lib.rs +++ b/rand_core/src/lib.rs @@ -481,6 +481,7 @@ impl<'a, R: CryptoRng + ?Sized> CryptoRng for &'a mut R {} // Implement `CryptoRng` for boxed references to a `CryptoRng`. #[cfg(feature = "alloc")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))] impl CryptoRng for Box {} #[cfg(test)] diff --git a/src/distributions/distribution.rs b/src/distributions/distribution.rs index 18ab30b886..175e355ac8 100644 --- a/src/distributions/distribution.rs +++ b/src/distributions/distribution.rs @@ -186,6 +186,7 @@ where /// Sampling a `String` of random characters is not quite the same as collecting /// a sequence of chars. This trait contains some helpers. #[cfg(feature = "alloc")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))] pub trait DistString { /// Append `len` random chars to `string` fn append_string(&self, rng: &mut R, string: &mut String, len: usize); diff --git a/src/distributions/float.rs b/src/distributions/float.rs index 4414cc7498..da7321ee86 100644 --- a/src/distributions/float.rs +++ b/src/distributions/float.rs @@ -90,8 +90,9 @@ pub trait IntoFloat { } macro_rules! float_impls { - ($ty:ident, $uty:ident, $f_scalar:ident, $u_scalar:ty, + ($($meta:meta)?, $ty:ident, $uty:ident, $f_scalar:ident, $u_scalar:ty, $fraction_bits:expr, $exponent_bias:expr) => { + $(#[cfg($meta)])? impl IntoFloat for $uty { type F = $ty; #[inline(always)] @@ -103,6 +104,8 @@ macro_rules! float_impls { } } + $(#[cfg($meta)] + #[cfg_attr(doc_cfg, doc(cfg($meta)))])? impl Distribution<$ty> for Standard { fn sample(&self, rng: &mut R) -> $ty { // Multiply-based method; 24/53 random bits; [0, 1) interval. @@ -118,6 +121,8 @@ macro_rules! float_impls { } } + $(#[cfg($meta)] + #[cfg_attr(doc_cfg, doc(cfg($meta)))])? impl Distribution<$ty> for OpenClosed01 { fn sample(&self, rng: &mut R) -> $ty { // Multiply-based method; 24/53 random bits; (0, 1] interval. @@ -134,6 +139,8 @@ macro_rules! float_impls { } } + $(#[cfg($meta)] + #[cfg_attr(doc_cfg, doc(cfg($meta)))])? impl Distribution<$ty> for Open01 { fn sample(&self, rng: &mut R) -> $ty { // Transmute-based method; 23/52 random bits; (0, 1) interval. @@ -150,24 +157,24 @@ macro_rules! float_impls { } } -float_impls! { f32, u32, f32, u32, 23, 127 } -float_impls! { f64, u64, f64, u64, 52, 1023 } +float_impls! { , f32, u32, f32, u32, 23, 127 } +float_impls! { , f64, u64, f64, u64, 52, 1023 } #[cfg(feature = "simd_support")] -float_impls! { f32x2, u32x2, f32, u32, 23, 127 } +float_impls! { feature = "simd_support", f32x2, u32x2, f32, u32, 23, 127 } #[cfg(feature = "simd_support")] -float_impls! { f32x4, u32x4, f32, u32, 23, 127 } +float_impls! { feature = "simd_support", f32x4, u32x4, f32, u32, 23, 127 } #[cfg(feature = "simd_support")] -float_impls! { f32x8, u32x8, f32, u32, 23, 127 } +float_impls! { feature = "simd_support", f32x8, u32x8, f32, u32, 23, 127 } #[cfg(feature = "simd_support")] -float_impls! { f32x16, u32x16, f32, u32, 23, 127 } +float_impls! { feature = "simd_support", f32x16, u32x16, f32, u32, 23, 127 } #[cfg(feature = "simd_support")] -float_impls! { f64x2, u64x2, f64, u64, 52, 1023 } +float_impls! { feature = "simd_support", f64x2, u64x2, f64, u64, 52, 1023 } #[cfg(feature = "simd_support")] -float_impls! { f64x4, u64x4, f64, u64, 52, 1023 } +float_impls! { feature = "simd_support", f64x4, u64x4, f64, u64, 52, 1023 } #[cfg(feature = "simd_support")] -float_impls! { f64x8, u64x8, f64, u64, 52, 1023 } +float_impls! { feature = "simd_support", f64x8, u64x8, f64, u64, 52, 1023 } #[cfg(test)] mod tests { diff --git a/src/distributions/integer.rs b/src/distributions/integer.rs index e5d320b255..8b9ae4ad40 100644 --- a/src/distributions/integer.rs +++ b/src/distributions/integer.rs @@ -124,8 +124,9 @@ impl_nzint!(NonZeroI128, NonZeroI128::new); impl_nzint!(NonZeroIsize, NonZeroIsize::new); macro_rules! x86_intrinsic_impl { - ($($intrinsic:ident),+) => {$( - /// Available only on x86/64 platforms + ($meta:meta, $($intrinsic:ident),+) => {$( + #[cfg($meta)] + #[cfg_attr(doc_cfg, doc(cfg($meta)))] impl Distribution<$intrinsic> for Standard { #[inline] fn sample(&self, rng: &mut R) -> $intrinsic { @@ -146,6 +147,9 @@ macro_rules! simd_impl { /// Requires nightly Rust and the [`simd_support`] feature /// /// [`simd_support`]: https://github.com/rust-random/rand#crate-features + #[cfg(feature = "simd_support")] + // TODO: as doc_cfg/doc_auto_cfg mature ensure they catch this + #[cfg_attr(doc_cfg, doc(cfg(feature = "simd_support")))] impl Distribution> for Standard where LaneCount: SupportedLaneCount, @@ -164,12 +168,22 @@ macro_rules! simd_impl { simd_impl!(u8, i8, u16, i16, u32, i32, u64, i64, usize, isize); #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] -x86_intrinsic_impl!(__m128i, __m256i); +x86_intrinsic_impl!( + any(target_arch = "x86", target_arch = "x86_64"), + __m128i, + __m256i +); #[cfg(all( any(target_arch = "x86", target_arch = "x86_64"), feature = "simd_support" ))] -x86_intrinsic_impl!(__m512i); +x86_intrinsic_impl!( + all( + any(target_arch = "x86", target_arch = "x86_64"), + feature = "simd_support" + ), + __m512i +); #[cfg(test)] mod tests { diff --git a/src/distributions/mod.rs b/src/distributions/mod.rs index 39d967d4f6..ee3615cf92 100644 --- a/src/distributions/mod.rs +++ b/src/distributions/mod.rs @@ -112,6 +112,7 @@ pub mod uniform; pub use self::bernoulli::{Bernoulli, BernoulliError}; pub use self::distribution::{Distribution, DistIter, DistMap}; #[cfg(feature = "alloc")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))] pub use self::distribution::DistString; pub use self::float::{Open01, OpenClosed01}; pub use self::other::Alphanumeric; diff --git a/src/distributions/other.rs b/src/distributions/other.rs index 596b8962c1..5b922bd37e 100644 --- a/src/distributions/other.rs +++ b/src/distributions/other.rs @@ -98,6 +98,7 @@ impl Distribution for Standard { /// Note: the `String` is potentially left with excess capacity; optionally the /// user may call `string.shrink_to_fit()` afterwards. #[cfg(feature = "alloc")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))] impl DistString for Standard { fn append_string(&self, rng: &mut R, s: &mut String, len: usize) { // A char is encoded with at most four bytes, thus this reservation is @@ -128,6 +129,7 @@ impl Distribution for Alphanumeric { } #[cfg(feature = "alloc")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))] impl DistString for Alphanumeric { fn append_string(&self, rng: &mut R, string: &mut String, len: usize) { unsafe { @@ -148,8 +150,6 @@ impl Distribution for Standard { } } -/// Requires nightly Rust and the [`simd_support`] feature -/// /// Note that on some hardware like x86/64 mask operations like [`_mm_blendv_epi8`] /// only care about a single bit. This means that you could use uniform random bits /// directly: @@ -177,6 +177,7 @@ impl Distribution for Standard { /// [`_mm_blendv_epi8`]: https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_blendv_epi8&ig_expand=514/ /// [`simd_support`]: https://github.com/rust-random/rand#crate-features #[cfg(feature = "simd_support")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "simd_support")))] impl Distribution> for Standard where T: MaskElement + Default, diff --git a/src/distributions/slice.rs b/src/distributions/slice.rs index 1c96680aa6..d49f45cceb 100644 --- a/src/distributions/slice.rs +++ b/src/distributions/slice.rs @@ -129,6 +129,7 @@ impl std::error::Error for EmptySlice {} /// Note: the `String` is potentially left with excess capacity; optionally the /// user may call `string.shrink_to_fit()` afterwards. #[cfg(feature = "alloc")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))] impl<'a> super::DistString for Slice<'a, char> { fn append_string(&self, rng: &mut R, string: &mut String, len: usize) { // Get the max char length to minimize extra space. diff --git a/src/distributions/uniform.rs b/src/distributions/uniform.rs index ecf90520b2..e69d5fe020 100644 --- a/src/distributions/uniform.rs +++ b/src/distributions/uniform.rs @@ -604,7 +604,7 @@ macro_rules! uniform_int_impl { let (mut result, mut lo) = rng.gen::<$sample_ty>().wmul(range); - // In constrast to the biased sampler, we use a loop: + // In contrast to the biased sampler, we use a loop: while lo > range.wrapping_neg() { let (new_hi, new_lo) = (rng.gen::<$sample_ty>()).wmul(range); match lo.checked_add(new_hi) { @@ -652,6 +652,9 @@ macro_rules! uniform_simd_int_impl { // know the PRNG's minimal output size, and casting to a larger vector // is generally a bad idea for SIMD performance. The user can still // implement it manually. + + #[cfg(feature = "simd_support")] + #[cfg_attr(doc_cfg, doc(cfg(feature = "simd_support")))] impl SampleUniform for Simd<$ty, LANES> where LaneCount: SupportedLaneCount, @@ -662,6 +665,8 @@ macro_rules! uniform_simd_int_impl { type Sampler = UniformInt>; } + #[cfg(feature = "simd_support")] + #[cfg_attr(doc_cfg, doc(cfg(feature = "simd_support")))] impl UniformSampler for UniformInt> where LaneCount: SupportedLaneCount, @@ -839,11 +844,12 @@ impl UniformSampler for UniformChar { } } -/// Note: the `String` is potentially left with excess capacity if the range -/// includes non ascii chars; optionally the user may call +/// Note: the `String` is potentially left with excess capacity if the range +/// includes non ascii chars; optionally the user may call /// `string.shrink_to_fit()` afterwards. #[cfg(feature = "alloc")] -impl super::DistString for Uniform{ +#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))] +impl super::DistString for Uniform { fn append_string(&self, rng: &mut R, string: &mut alloc::string::String, len: usize) { // Getting the hi value to assume the required length to reserve in string. let mut hi = self.0.sampler.low + self.0.sampler.range - 1; @@ -884,11 +890,15 @@ pub struct UniformFloat { } macro_rules! uniform_float_impl { - ($ty:ty, $uty:ident, $f_scalar:ident, $u_scalar:ident, $bits_to_discard:expr) => { + ($($meta:meta)?, $ty:ty, $uty:ident, $f_scalar:ident, $u_scalar:ident, $bits_to_discard:expr) => { + $(#[cfg($meta)] + #[cfg_attr(doc_cfg, doc(cfg($meta)))])? impl SampleUniform for $ty { type Sampler = UniformFloat<$ty>; } + $(#[cfg($meta)] + #[cfg_attr(doc_cfg, doc(cfg($meta)))])? impl UniformSampler for UniformFloat<$ty> { type X = $ty; @@ -1088,24 +1098,24 @@ macro_rules! uniform_float_impl { }; } -uniform_float_impl! { f32, u32, f32, u32, 32 - 23 } -uniform_float_impl! { f64, u64, f64, u64, 64 - 52 } +uniform_float_impl! { , f32, u32, f32, u32, 32 - 23 } +uniform_float_impl! { , f64, u64, f64, u64, 64 - 52 } #[cfg(feature = "simd_support")] -uniform_float_impl! { f32x2, u32x2, f32, u32, 32 - 23 } +uniform_float_impl! { feature = "simd_support", f32x2, u32x2, f32, u32, 32 - 23 } #[cfg(feature = "simd_support")] -uniform_float_impl! { f32x4, u32x4, f32, u32, 32 - 23 } +uniform_float_impl! { feature = "simd_support", f32x4, u32x4, f32, u32, 32 - 23 } #[cfg(feature = "simd_support")] -uniform_float_impl! { f32x8, u32x8, f32, u32, 32 - 23 } +uniform_float_impl! { feature = "simd_support", f32x8, u32x8, f32, u32, 32 - 23 } #[cfg(feature = "simd_support")] -uniform_float_impl! { f32x16, u32x16, f32, u32, 32 - 23 } +uniform_float_impl! { feature = "simd_support", f32x16, u32x16, f32, u32, 32 - 23 } #[cfg(feature = "simd_support")] -uniform_float_impl! { f64x2, u64x2, f64, u64, 64 - 52 } +uniform_float_impl! { feature = "simd_support", f64x2, u64x2, f64, u64, 64 - 52 } #[cfg(feature = "simd_support")] -uniform_float_impl! { f64x4, u64x4, f64, u64, 64 - 52 } +uniform_float_impl! { feature = "simd_support", f64x4, u64x4, f64, u64, 64 - 52 } #[cfg(feature = "simd_support")] -uniform_float_impl! { f64x8, u64x8, f64, u64, 64 - 52 } +uniform_float_impl! { feature = "simd_support", f64x8, u64x8, f64, u64, 64 - 52 } /// The back-end implementing [`UniformSampler`] for `Duration`. diff --git a/src/seq/mod.rs b/src/seq/mod.rs index 908021ad3d..8d19e57df2 100644 --- a/src/seq/mod.rs +++ b/src/seq/mod.rs @@ -637,17 +637,17 @@ impl SliceRandom for [T] { // for an unbiased permutation. // It ensures that the last `amount` elements of the slice // are randomly selected from the whole slice. - - //`IncreasingUniform::next_index()` is faster than `gen_index` - //but only works for 32 bit integers - //So we must use the slow method if the slice is longer than that. + + // `IncreasingUniform::next_index()` is faster than `gen_index` + // but only works for 32 bit integers + // So we must use the slow method if the slice is longer than that. if self.len() < (u32::MAX as usize) { let mut chooser = IncreasingUniform::new(rng, m as u32); for i in m..self.len() { let index = chooser.next_index(); self.swap(i, index); } - } else { + } else { for i in m..self.len() { let index = gen_index(rng, i + 1); self.swap(i, index); @@ -674,6 +674,7 @@ pub struct SliceChooseIter<'a, S: ?Sized + 'a, T: 'a> { } #[cfg(feature = "alloc")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))] impl<'a, S: Index + ?Sized + 'a, T: 'a> Iterator for SliceChooseIter<'a, S, T> { type Item = &'a T; @@ -688,6 +689,7 @@ impl<'a, S: Index + ?Sized + 'a, T: 'a> Iterator for SliceCho } #[cfg(feature = "alloc")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))] impl<'a, S: Index + ?Sized + 'a, T: 'a> ExactSizeIterator for SliceChooseIter<'a, S, T> { @@ -701,7 +703,6 @@ impl<'a, S: Index + ?Sized + 'a, T: 'a> ExactSizeIterator // platforms. #[inline] fn gen_index(rng: &mut R, ubound: usize) -> usize { - if ubound <= (core::u32::MAX as usize) { rng.gen_range(0..ubound as u32) as usize } else {