Document the feature flags

Cargo.lock

@@ -638,6 +638,15 @@ dependencies = [
  "subtle",
 ]
 
+[[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"
@@ -1237,6 +1246,12 @@ version = "0.4.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "969488b55f8ac402214f3f5fd243ebb7206cf82de60d3172994707a4bcc2b829"
 
+[[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"
@@ -2087,7 +2102,7 @@ dependencies = [
 [[package]]
 name = "sapling-crypto"
 version = "0.0.1"
-source = "git+https://github.com/zcash/sapling-crypto.git?rev=71711b9e4b775a625318070e0f56b7b652f12306#71711b9e4b775a625318070e0f56b7b652f12306"
+source = "git+https://github.com/zcash/sapling-crypto.git?rev=4ec6a48daab0af1fe6cb930f6a150030ce91d0e9#4ec6a48daab0af1fe6cb930f6a150030ce91d0e9"
 dependencies = [
  "aes",
  "bellman",
@@ -2096,6 +2111,7 @@ dependencies = [
  "blake2s_simd",
  "bls12_381",
  "byteorder",
+ "document-features",
  "ff",
  "fpe",
  "group",
@@ -2995,6 +3011,7 @@ dependencies = [
  "bs58",
  "byteorder",
  "crossbeam-channel",
+ "document-features",
  "group",
  "gumdrop",
  "hdwallet",
@@ -3033,6 +3050,7 @@ dependencies = [
  "assert_matches",
  "bs58",
  "byteorder",
+ "document-features",
  "group",
  "hdwallet",
  "incrementalmerkletree",
@@ -3118,6 +3136,7 @@ dependencies = [
  "byteorder",
  "chacha20poly1305",
  "criterion",
+ "document-features",
  "equihash",
  "ff",
  "fpe",
@@ -3156,6 +3175,7 @@ dependencies = [
  "blake2b_simd",
  "bls12_381",
  "byteorder",
+ "document-features",
  "group",
  "home",
  "jubjub",

Cargo.toml

@@ -66,6 +66,9 @@ rand_core = "0.6"
 blake2b_simd = "1"
 sha2 = "0.10"
 
+# Documentation
+document-features = "0.2"
+
 # Encodings
 base64 = "0.21"
 bech32 = "0.9"
@@ -112,5 +115,5 @@ panic = 'abort'
 codegen-units = 1
 
 [patch.crates-io]
-sapling = { package = "sapling-crypto", git = "https://github.com/zcash/sapling-crypto.git", rev = "71711b9e4b775a625318070e0f56b7b652f12306" }
+sapling = { package = "sapling-crypto", git = "https://github.com/zcash/sapling-crypto.git", rev = "4ec6a48daab0af1fe6cb930f6a150030ce91d0e9" }
 orchard = { git = "https://github.com/zcash/orchard.git", rev = "189257391a5726d7f3f2568d547a5ef8603c7156" }

zcash_client_backend/Cargo.toml

@@ -74,6 +74,9 @@ nom = "7"
 
 # Dependencies used internally:
 # (Breaking upgrades to these are usually backwards-compatible, but check MSRVs.)
+# - Documentation
+document-features.workspace = true
+
 # - Encodings
 byteorder = { workspace = true, optional = true }
 percent-encoding.workspace = true
@@ -100,16 +103,29 @@ zcash_address = { workspace = true, features = ["test-dependencies"] }
 time = ">=0.3.22, <0.3.24" # time 0.3.24 has MSRV 1.67
 
 [features]
+## Enables the `tonic` gRPC client bindings for connecting to a `lightwalletd` server.
 lightwalletd-tonic = ["dep:tonic"]
+
+## Enables receiving transparent funds and shielding them.
 transparent-inputs = ["dep:hdwallet", "zcash_primitives/transparent-inputs"]
+
+## Exposes APIs that are useful for testing, such as `proptest` strategies.
 test-dependencies = [
     "dep:proptest",
     "orchard/test-dependencies",
     "zcash_primitives/test-dependencies",
-    "incrementalmerkletree/test-dependencies"
+    "incrementalmerkletree/test-dependencies",
 ]
+
+#! ### Experimental features
+
+## Exposes unstable APIs. Their behaviour may change at any time.
 unstable = ["dep:byteorder"]
+
+## Exposes APIs for unstable serialization formats. These may change at any time.
 unstable-serialization = ["dep:byteorder"]
+
+## Exposes the [`data_api::scanning::spanning_tree`] module.
 unstable-spanning-tree = []
 
 [lib]

zcash_client_backend/src/lib.rs

@@ -2,6 +2,10 @@
 //!
 //! `zcash_client_backend` contains Rust structs and traits for creating shielded Zcash
 //! light clients.
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 // Catch documentation errors caused by code changes.
 #![deny(rustdoc::broken_intra_doc_links)]

zcash_client_sqlite/Cargo.toml

@@ -53,6 +53,7 @@ uuid = "1.1"
 
 # Dependencies used internally:
 # (Breaking upgrades to these are usually backwards-compatible, but check MSRVs.)
+document-features.workspace = true
 maybe-rayon.workspace = true
 
 [dev-dependencies]
@@ -71,15 +72,28 @@ zcash_address = { workspace = true, features = ["test-dependencies"] }
 
 [features]
 default = ["multicore"]
+
+## Enables multithreading support for creating proofs and building subtrees.
 multicore = ["maybe-rayon/threads", "zcash_primitives/multicore"]
+
+## Configures the light client for use with the Zcash mainnet. By default, the light
+## client is configured for use with the Zcash testnet.
 mainnet = []
+
+## Exposes APIs that are useful for testing, such as `proptest` strategies.
 test-dependencies = [
     "incrementalmerkletree/test-dependencies",
     "zcash_primitives/test-dependencies",
     "zcash_client_backend/test-dependencies",
     "incrementalmerkletree/test-dependencies",
 ]
+
+## Enables receiving transparent funds and shielding them.
 transparent-inputs = ["dep:hdwallet", "zcash_client_backend/transparent-inputs"]
+
+#! ### Experimental features
+
+## Exposes unstable APIs. Their behaviour may change at any time.
 unstable = ["zcash_client_backend/unstable"]
 
 [lib]

zcash_client_sqlite/src/lib.rs

@@ -18,10 +18,8 @@
 //!   **MUST NOT** write to the database without using these APIs. Callers **MAY** read
 //!   the database directly in order to extract information for display to users.
 //!
-//! # Features
-//!
-//! The `mainnet` feature configures the light client for use with the Zcash mainnet. By
-//! default, the light client is configured for use with the Zcash testnet.
+//! ## Feature flags
+#![doc = document_features::document_features!()]
 //!
 //! [`WalletRead`]: zcash_client_backend::data_api::WalletRead
 //! [`WalletWrite`]: zcash_client_backend::data_api::WalletWrite

zcash_primitives/Cargo.toml

@@ -66,6 +66,9 @@ bip0039 = { version = "0.10", features = ["std", "all-languages"] }
 
 # Dependencies used internally:
 # (Breaking upgrades to these are usually backwards-compatible, but check MSRVs.)
+# - Documentation
+document-features.workspace = true
+
 # - Encodings
 byteorder.workspace = true
 hex.workspace = true
@@ -99,15 +102,33 @@ pprof = { version = "0.11", features = ["criterion", "flamegraph"] } # MSRV 1.56
 
 [features]
 default = ["multicore"]
+
+## Enables multithreading support for creating proofs.
 multicore = ["orchard/multicore", "sapling/multicore"]
+
+## Enables spending transparent notes with the transaction builder.
 transparent-inputs = ["dep:hdwallet", "dep:ripemd", "dep:secp256k1"]
+
+### 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 = [
     "dep:proptest",
     "orchard/test-dependencies",
     "sapling/test-dependencies",
 ]
+
+#! ### Experimental features
+#!
+#! ⚠️ Enabling these features will likely make your code incompatible with current Zcash
+#! consensus rules!
+
+## Exposes the in-development NU6 features.
 unstable-nu6 = []
+
+## Exposes early in-development features that are not yet planned for any network upgrade.
 zfuture = []
 
 [lib]

zcash_primitives/src/lib.rs

@@ -2,6 +2,10 @@
 //!
 //! `zcash_primitives` is a library that provides the core structs and functions necessary
 //! for working with Zcash.
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
 // Catch documentation errors caused by code changes.

zcash_proofs/Cargo.toml

@@ -34,6 +34,7 @@ tracing.workspace = true
 # Dependencies used internally:
 # (Breaking upgrades to these are usually backwards-compatible, but check MSRVs.)
 blake2b_simd.workspace = true
+document-features.workspace = true
 home = { version = "0.5", optional = true }
 known-folders = { version = "1", optional = true }
 redjubjub = "0.7"
@@ -45,10 +46,24 @@ byteorder.workspace = true
 
 [features]
 default = ["local-prover", "multicore"]
+
+## Bundles the Sapling proving parameters inside the binary, which will increase its size
+## by around 50 MiB.
 bundled-prover = ["dep:wagyu-zcash-parameters"]
+
+## Enables APIs for determining the default location on the local filesystem for storing
+## the Sprout and Sapling proving parameters.
 directories = ["dep:home", "dep:known-folders", "dep:xdg"]
+
+## Enables APIs for downloading the Sprout and Sapling proving parameters to the default
+## location on the local filesystem.
 download-params = ["dep:minreq", "directories"]
+
+## Enables APIs for loading the Sapling proving parameters from the default location on
+## the local filesystem.
 local-prover = ["directories"]
+
+## Enables multithreading support for creating proofs.
 multicore = ["bellman/multicore", "zcash_primitives/multicore"]
 
 [lib]

zcash_proofs/src/lib.rs

@@ -2,6 +2,10 @@
 //!
 //! `zcash_proofs` contains the zk-SNARK circuits used by Zcash, and the APIs for creating
 //! and verifying proofs.
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
+//!
 
 #![cfg_attr(docsrs, feature(doc_cfg))]
 // Catch documentation errors caused by code changes.