From 314930e92db9ac99fdd2a1b795c4cc7fd79419e3 Mon Sep 17 00:00:00 2001
From: Jack Grigg <jack@electriccoin.co>
Date: Wed, 3 Jan 2024 18:14:06 +0000
Subject: [PATCH] Document feature flags

---
 Cargo.lock     | 16 ++++++++++++++++
 Cargo.toml     | 15 ++++++++++++++-
 src/builder.rs |  2 +-
 src/bundle.rs  |  1 +
 src/keys.rs    |  1 +
 src/lib.rs     |  6 ++++++
 src/prover.rs  |  1 +
 src/zip32.rs   |  1 +
 8 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index b71a49b..2c46b31 100644
--- a/Cargo.lock
+++ b/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",
diff --git a/Cargo.toml b/Cargo.toml
index d88e63f..685312e 100644
--- a/Cargo.toml
+++ b/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]]
diff --git a/src/builder.rs b/src/builder.rs
index b516cb5..4ca4dc3 100644
--- a/src/builder.rs
+++ b/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;
diff --git a/src/bundle.rs b/src/bundle.rs
index 0567c5e..c8fedbb 100644
--- a/src/bundle.rs
+++ b/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;
 
diff --git a/src/keys.rs b/src/keys.rs
index 9bc3a6d..61dc6f8 100644
--- a/src/keys.rs
+++ b/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::*;
diff --git a/src/lib.rs b/src/lib.rs
index 5efd031..5ffc49b 100644
--- a/src/lib.rs
+++ b/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,
diff --git a/src/prover.rs b/src/prover.rs
index 9694deb..d9b874c 100644
--- a/src/prover.rs
+++ b/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;
 
diff --git a/src/zip32.rs b/src/zip32.rs
index 5f70316..f4a8dad 100644
--- a/src/zip32.rs
+++ b/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};