Document feature flags

Cargo.lock

@@ -459,6 +459,15 @@ dependencies = [
  "uuid",
 ]
 
+[[package]]
+name = "document-features"
+version = "0.2.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef5282ad69563b5fc40319526ba27e0e7363d552a896f0297d54f767717f9b95"
+dependencies = [
+ "litrs",
+]
+
 [[package]]
 name = "either"
 version = "1.9.0"
@@ -744,6 +753,12 @@ version = "0.4.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c4cd1a83af159aa67994778be9070f0ae1bd732942279cabb14f86f986a21456"
 
+[[package]]
+name = "litrs"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4ce301924b7887e9d637144fdade93f9dfff9b60981d4ac161db09720d39aa5"
+
 [[package]]
 name = "lock_api"
 version = "0.4.11"
@@ -1267,6 +1282,7 @@ dependencies = [
  "byteorder",
  "chacha20poly1305",
  "criterion",
+ "document-features",
  "ff",
  "fpe",
  "group",

Cargo.toml

@@ -13,6 +13,10 @@ homepage = "https://github.com/zcash/sapling-crypto"
 repository = "https://github.com/zcash/sapling-crypto"
 license = "MIT OR Apache-2.0"
 
+[package.metadata.docs.rs]
+features = ["test-dependencies"]
+rustdoc-args = ["--cfg", "docsrs"]
+
 [dependencies]
 ff = "0.13"
 group = { version = "0.13", features = ["wnaf-memuse"] }
@@ -33,6 +37,9 @@ rand_core = "0.6"
 blake2b_simd = "1"
 blake2s_simd = "1"
 
+# Documentation
+document-features = "0.2"
+
 # Encodings
 byteorder = "1"
 hex = "0.4"
@@ -73,11 +80,17 @@ rand_xorshift = "0.3"
 pprof = { version = "0.11", features = ["criterion", "flamegraph"] } # MSRV 1.56
 
 [features]
+## Enables multithreading support for creating proofs.
 multicore = ["bellman/multicore"]
+
+### A temporary feature flag that exposes granular APIs needed by `zcashd`. These APIs
+### should not be relied upon and will be removed in a future release.
 temporary-zcashd = []
+
+## Exposes APIs that are useful for testing, such as `proptest` strategies.
 test-dependencies = [
     "incrementalmerkletree/test-dependencies",
-    "proptest",
+    "dep:proptest",
 ]
 
 [[bench]]

src/builder.rs

@@ -1065,7 +1065,7 @@ impl<V> Bundle<InProgress<Proven, PartiallyAuthorized>, V> {
 }
 
 #[cfg(any(test, feature = "test-dependencies"))]
-pub mod testing {
+pub(crate) mod testing {
     use std::fmt;
 
     use proptest::collection::vec;

src/bundle.rs

@@ -483,6 +483,7 @@ impl<A> From<OutputDescription<A>> for CompactOutputDescription {
 }
 
 #[cfg(any(test, feature = "test-dependencies"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "test-dependencies")))]
 pub mod testing {
     use std::fmt;
 

src/keys.rs

@@ -662,6 +662,7 @@ impl SharedSecret {
 }
 
 #[cfg(any(test, feature = "test-dependencies"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "test-dependencies")))]
 pub mod testing {
     use proptest::collection::vec;
     use proptest::prelude::*;

src/lib.rs

@@ -6,7 +6,12 @@
 //! Sapling-specific types. For example, [`PaymentAddress`] is documented as being a
 //! shielded payment address; we implicitly mean it is an Sapling payment address (as
 //! opposed to e.g. an Orchard payment address, which is also shielded).
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
+#![cfg_attr(docsrs, feature(doc_cfg))]
 // Catch documentation errors caused by code changes.
 #![deny(rustdoc::broken_intra_doc_links)]
 #![deny(unsafe_code)]
@@ -40,6 +45,7 @@ pub use tree::{
 pub use verifier::{BatchValidator, SaplingVerificationContext};
 
 #[cfg(any(test, feature = "test-dependencies"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "test-dependencies")))]
 pub mod testing {
     pub use super::{
         address::testing::arb_payment_address, keys::testing::arb_incoming_viewing_key,

src/prover.rs

@@ -171,6 +171,7 @@ impl OutputProver for OutputParameters {
 }
 
 #[cfg(any(test, feature = "test-dependencies"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "test-dependencies")))]
 pub mod mock {
     use ff::Field;
 

src/zip32.rs

@@ -1718,6 +1718,7 @@ mod tests {
 }
 
 #[cfg(any(test, feature = "test-dependencies"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "test-dependencies")))]
 pub mod testing {
     use proptest::collection::vec;
     use proptest::prelude::{any, prop_compose};