Merge pull request #306 from cuviper/docsrs

Add feature cfgs for docs.rs

.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.

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"

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)]

src/bigint/arbitrary.rs

@@ -1,10 +1,13 @@
+#![cfg(any(feature = "quickcheck", feature = "arbitrary"))]
+
 use super::{BigInt, Sign};
 use crate::BigUint;
 
 #[cfg(feature = "quickcheck")]
 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<Self> {
         let positive = bool::arbitrary(u)?;

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};

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::*;

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};

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<Self> {
         Ok(biguint_from_vec(Vec::<BigDigit>::arbitrary(u)?))

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;

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<T> TryFromBigIntError<T> {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
 impl<T> std::error::Error for TryFromBigIntError<T>
 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 {