From 52175ce0612462765a2932d9d86f57237d27eba6 Mon Sep 17 00:00:00 2001 From: Josh Stone Date: Fri, 10 May 2024 14:55:19 -0700 Subject: [PATCH] Add feature cfgs for docs.rs --- .github/workflows/ci.yaml | 12 +++++++++++- Cargo.toml | 1 + src/bigint.rs | 8 ++------ src/bigint/arbitrary.rs | 4 ++++ src/bigint/serde.rs | 3 +++ src/bigrand.rs | 2 ++ src/biguint.rs | 8 ++------ src/biguint/arbitrary.rs | 4 ++++ src/biguint/serde.rs | 3 +++ src/lib.rs | 20 +++++++++++++++++--- 10 files changed, 49 insertions(+), 16 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 8ddca545..ede5aaed 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -63,12 +63,22 @@ jobs: components: rustfmt - run: cargo fmt --all --check + doc: + name: Docs.rs + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@nightly + - run: cargo doc --features std,serde,rand,quickcheck,arbitrary + env: + RUSTDOCFLAGS: --cfg docsrs + # One job that "summarizes" the success state of this pipeline. This can then be added to branch # protection, rather than having to add each job separately. success: name: Success runs-on: ubuntu-latest - needs: [test, i686, no_std, fmt] + needs: [test, i686, no_std, fmt, doc] # Github branch protection is exceedingly silly and treats "jobs skipped because a dependency # failed" as success. So we have to do some contortions to ensure the job fails if any of its # dependencies fails. diff --git a/Cargo.toml b/Cargo.toml index cd1e6d2b..ff41e8a9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -24,6 +24,7 @@ serde = ["dep:serde"] [package.metadata.docs.rs] features = ["std", "serde", "rand", "quickcheck", "arbitrary"] +rustdoc-args = ["--cfg", "docsrs"] [[bench]] name = "bigint" diff --git a/src/bigint.rs b/src/bigint.rs index 76b64fbb..b4f84b9e 100644 --- a/src/bigint.rs +++ b/src/bigint.rs @@ -24,16 +24,12 @@ mod division; mod multiplication; mod subtraction; +mod arbitrary; mod bits; mod convert; mod power; -mod shift; - -#[cfg(any(feature = "quickcheck", feature = "arbitrary"))] -mod arbitrary; - -#[cfg(feature = "serde")] mod serde; +mod shift; /// A `Sign` is a [`BigInt`]'s composing element. #[derive(PartialEq, PartialOrd, Eq, Ord, Copy, Clone, Debug, Hash)] diff --git a/src/bigint/arbitrary.rs b/src/bigint/arbitrary.rs index 6b809cae..3cb90b30 100644 --- a/src/bigint/arbitrary.rs +++ b/src/bigint/arbitrary.rs @@ -1,3 +1,5 @@ +#![cfg(any(feature = "quickcheck", feature = "arbitrary"))] + use super::{BigInt, Sign}; use crate::BigUint; @@ -5,6 +7,7 @@ use crate::BigUint; use alloc::boxed::Box; #[cfg(feature = "quickcheck")] +#[cfg_attr(docsrs, doc(cfg(feature = "quickcheck")))] impl quickcheck::Arbitrary for BigInt { fn arbitrary(g: &mut quickcheck::Gen) -> Self { let positive = bool::arbitrary(g); @@ -20,6 +23,7 @@ impl quickcheck::Arbitrary for BigInt { } #[cfg(feature = "arbitrary")] +#[cfg_attr(docsrs, doc(cfg(feature = "arbitrary")))] impl arbitrary::Arbitrary<'_> for BigInt { fn arbitrary(u: &mut arbitrary::Unstructured<'_>) -> arbitrary::Result { let positive = bool::arbitrary(u)?; diff --git a/src/bigint/serde.rs b/src/bigint/serde.rs index 5c232f94..6c476920 100644 --- a/src/bigint/serde.rs +++ b/src/bigint/serde.rs @@ -1,3 +1,6 @@ +#![cfg(feature = "serde")] +#![cfg_attr(docsrs, doc(cfg(feature = "serde")))] + use super::{BigInt, Sign}; use serde::de::{Error, Unexpected}; diff --git a/src/bigrand.rs b/src/bigrand.rs index 0b1cb23c..e5cbacdb 100644 --- a/src/bigrand.rs +++ b/src/bigrand.rs @@ -1,4 +1,6 @@ //! Randomization of big integers +#![cfg(feature = "rand")] +#![cfg_attr(docsrs, doc(cfg(feature = "rand")))] use rand::distributions::uniform::{SampleBorrow, SampleUniform, UniformSampler}; use rand::prelude::*; diff --git a/src/biguint.rs b/src/biguint.rs index a3bfdcd3..196fa323 100644 --- a/src/biguint.rs +++ b/src/biguint.rs @@ -18,18 +18,14 @@ mod division; mod multiplication; mod subtraction; +mod arbitrary; mod bits; mod convert; mod iter; mod monty; mod power; -mod shift; - -#[cfg(any(feature = "quickcheck", feature = "arbitrary"))] -mod arbitrary; - -#[cfg(feature = "serde")] mod serde; +mod shift; pub(crate) use self::convert::to_str_radix_reversed; pub use self::iter::{U32Digits, U64Digits}; diff --git a/src/biguint/arbitrary.rs b/src/biguint/arbitrary.rs index 76099bc4..9d5c5ccf 100644 --- a/src/biguint/arbitrary.rs +++ b/src/biguint/arbitrary.rs @@ -1,3 +1,5 @@ +#![cfg(any(feature = "quickcheck", feature = "arbitrary"))] + use super::{biguint_from_vec, BigUint}; use crate::big_digit::BigDigit; @@ -6,6 +8,7 @@ use alloc::boxed::Box; use alloc::vec::Vec; #[cfg(feature = "quickcheck")] +#[cfg_attr(docsrs, doc(cfg(feature = "quickcheck")))] impl quickcheck::Arbitrary for BigUint { fn arbitrary(g: &mut quickcheck::Gen) -> Self { // Use arbitrary from Vec @@ -19,6 +22,7 @@ impl quickcheck::Arbitrary for BigUint { } #[cfg(feature = "arbitrary")] +#[cfg_attr(docsrs, doc(cfg(feature = "arbitrary")))] impl arbitrary::Arbitrary<'_> for BigUint { fn arbitrary(u: &mut arbitrary::Unstructured<'_>) -> arbitrary::Result { Ok(biguint_from_vec(Vec::::arbitrary(u)?)) diff --git a/src/biguint/serde.rs b/src/biguint/serde.rs index f0f792be..84bdf505 100644 --- a/src/biguint/serde.rs +++ b/src/biguint/serde.rs @@ -1,3 +1,6 @@ +#![cfg(feature = "serde")] +#![cfg_attr(docsrs, doc(cfg(feature = "serde")))] + use super::{biguint_from_vec, BigUint}; use alloc::vec::Vec; diff --git a/src/lib.rs b/src/lib.rs index e9d2a048..671d544b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -78,11 +78,24 @@ //! Note that you must use the version of `rand` that `num-bigint` is compatible //! with: `0.8`. //! +//! ### Arbitrary Big Integers +//! +//! `num-bigint` supports `arbitrary` and `quickcheck` features to implement +//! [`arbitrary::Arbitrary`] and [`quickcheck::Arbitrary`], respectively, for both `BigInt` and +//! `BigUint`. These are useful for fuzzing and other forms of randomized testing. +//! +//! ### Serialization +//! +//! The `serde` feature adds implementations of [`Serialize`][serde::Serialize] and +//! [`Deserialize`][serde::Deserialize] for both `BigInt` and `BigUint`. Their serialized data is +//! generated portably, regardless of platform differences like the internal digit size. +//! //! //! ## Compatibility //! //! The `num-bigint` crate is tested for rustc 1.60 and greater. +#![cfg_attr(docsrs, feature(doc_cfg))] #![doc(html_root_url = "https://docs.rs/num-bigint/0.4")] #![warn(rust_2018_idioms)] #![no_std] @@ -99,10 +112,8 @@ use core::fmt; mod macros; mod bigint; -mod biguint; - -#[cfg(feature = "rand")] mod bigrand; +mod biguint; #[cfg(target_pointer_width = "32")] type UsizePromotion = u32; @@ -154,6 +165,7 @@ impl fmt::Display for ParseBigIntError { } #[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] impl std::error::Error for ParseBigIntError { fn description(&self) -> &str { self.__description() @@ -183,6 +195,7 @@ impl TryFromBigIntError { } #[cfg(feature = "std")] +#[cfg_attr(docsrs, doc(cfg(feature = "std")))] impl std::error::Error for TryFromBigIntError where T: fmt::Debug, @@ -208,6 +221,7 @@ pub use crate::bigint::Sign; pub use crate::bigint::ToBigInt; #[cfg(feature = "rand")] +#[cfg_attr(docsrs, doc(cfg(feature = "rand")))] pub use crate::bigrand::{RandBigInt, RandomBits, UniformBigInt, UniformBigUint}; mod big_digit {