Merge pull request #1730 from zcash/1728-fix-docs

Fix crate documentation

components/equihash/CHANGELOG.md

@@ -7,6 +7,10 @@ and this library adheres to Rust's notion of
 
 ## [Unreleased]
 
+## [0.2.2] - 2025-03-04
+
+Documentation improvements and rendering fix; no code changes.
+
 ## [0.2.1] - 2025-02-21
 ### Added
 - `equihash::tromp` module behind the experimental `solver` feature flag.

components/equihash/Cargo.toml

@@ -1,25 +1,34 @@
 [package]
 name = "equihash"
 description = "The Equihash Proof-of-Work function"
-version = "0.2.1"
+version = "0.2.2"
 authors = ["Jack Grigg <jack@z.cash>"]
 homepage = "https://github.com/zcash/librustzcash"
 repository = "https://github.com/zcash/librustzcash"
 license = "MIT OR Apache-2.0"
 edition = "2021"
 rust-version = "1.56.1"
 
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
 [features]
 default = ["std"]
-std = []
+std = ["document-features"]
 
-# Experimental tromp solver support, builds the C++ tromp solver and Rust FFI layer.
+## Experimental tromp solver support, builds the C++ tromp solver and Rust FFI layer.
 solver = ["dep:cc", "std"]
 
 [dependencies]
 core2.workspace = true
 blake2b_simd.workspace = true
 
+# Dependencies used internally:
+# (Breaking upgrades to these are usually backwards-compatible, but check MSRVs.)
+# - Documentation
+document-features = { workspace = true, optional = true }
+
 [build-dependencies]
 cc = { version = "1", optional = true }
 

components/equihash/src/lib.rs

@@ -7,6 +7,9 @@
 //! verify solutions for any valid `(n, k)` parameters, as long as the row indices are no
 //! larger than 32 bits (that is, `ceiling(((n / (k + 1)) + 1) / 8) <= 4`).
 //!
+#![cfg_attr(feature = "std", doc = "## Feature flags")]
+#![cfg_attr(feature = "std", doc = document_features::document_features!())]
+//!
 //! References
 //! ==========
 //! - [Section 7.6.1: Equihash.] Zcash Protocol Specification, version 2020.1.10 or later.
@@ -20,6 +23,8 @@
 // Catch documentation errors caused by code changes.
 #![deny(rustdoc::broken_intra_doc_links)]
 #![no_std]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 #[cfg(feature = "std")]
 extern crate std;

components/zcash_address/src/lib.rs

@@ -184,8 +184,8 @@ impl ZcashAddress {
     /// [ZIP 316](https://zips.z.cash/zip-0316). The [`Display` implementation] can also
     /// be used to produce this encoding using [`address.to_string()`].
     ///
-    /// [`Display` implementation]: std::fmt::Display
-    /// [`address.to_string()`]: std::string::ToString
+    /// [`Display` implementation]: core::fmt::Display
+    /// [`address.to_string()`]: alloc::string::ToString
     pub fn encode(&self) -> String {
         format!("{}", self)
     }
@@ -194,7 +194,7 @@ impl ZcashAddress {
     ///
     /// This simply calls [`s.parse()`], leveraging the [`FromStr` implementation].
     ///
-    /// [`s.parse()`]: std::primitive::str::parse
+    /// [`s.parse()`]: str::parse
     /// [`FromStr` implementation]: ZcashAddress#impl-FromStr
     ///
     /// # Errors
@@ -229,8 +229,8 @@ impl ZcashAddress {
     /// method or the [`Display` implementation] via [`address.to_string()`] instead.
     ///
     /// [`encode`]: Self::encode
-    /// [`Display` implementation]: std::fmt::Display
-    /// [`address.to_string()`]: std::string::ToString
+    /// [`Display` implementation]: core::fmt::Display
+    /// [`address.to_string()`]: alloc::string::ToString
     pub fn convert<T: TryFromAddress>(self) -> Result<T, ConversionError<T::Error>> {
         match self.kind {
             AddressKind::Sprout(data) => T::try_from_sprout(self.net, data),
@@ -254,8 +254,8 @@ impl ZcashAddress {
     /// method or the [`Display` implementation] via [`address.to_string()`] instead.
     ///
     /// [`encode`]: Self::encode
-    /// [`Display` implementation]: std::fmt::Display
-    /// [`address.to_string()`]: std::string::ToString
+    /// [`Display` implementation]: core::fmt::Display
+    /// [`address.to_string()`]: alloc::string::ToString
     pub fn convert_if_network<T: TryFromRawAddress>(
         self,
         net: NetworkType,

components/zcash_protocol/src/consensus.rs

@@ -138,7 +138,6 @@ pub trait NetworkConstants: Clone {
     ///
     /// Defined in [ZIP 32].
     ///
-    /// [`ExtendedSpendingKey`]: zcash_primitives::zip32::ExtendedSpendingKey
     /// [ZIP 32]: https://github.com/zcash/zips/blob/master/zip-0032.rst
     fn hrp_sapling_extended_spending_key(&self) -> &'static str;
 
@@ -147,7 +146,6 @@ pub trait NetworkConstants: Clone {
     ///
     /// Defined in [ZIP 32].
     ///
-    /// [`ExtendedFullViewingKey`]: zcash_primitives::zip32::ExtendedFullViewingKey
     /// [ZIP 32]: https://github.com/zcash/zips/blob/master/zip-0032.rst
     fn hrp_sapling_extended_full_viewing_key(&self) -> &'static str;
 
@@ -156,7 +154,6 @@ pub trait NetworkConstants: Clone {
     ///
     /// Defined in section 5.6.4 of the [Zcash Protocol Specification].
     ///
-    /// [`PaymentAddress`]: zcash_primitives::primitives::PaymentAddress
     /// [Zcash Protocol Specification]: https://github.com/zcash/zips/blob/master/protocol/protocol.pdf
     fn hrp_sapling_payment_address(&self) -> &'static str;
 
@@ -172,14 +169,10 @@ pub trait NetworkConstants: Clone {
     /// Returns the human-readable prefix for Base58Check-encoded transparent
     /// pay-to-public-key-hash payment addresses for the network to which this NetworkConstants value
     /// applies.
-    ///
-    /// [`TransparentAddress::PublicKey`]: zcash_primitives::legacy::TransparentAddress::PublicKey
     fn b58_pubkey_address_prefix(&self) -> [u8; 2];
 
     /// Returns the human-readable prefix for Base58Check-encoded transparent pay-to-script-hash
     /// payment addresses for the network to which this NetworkConstants value applies.
-    ///
-    /// [`TransparentAddress::Script`]: zcash_primitives::legacy::TransparentAddress::Script
     fn b58_script_address_prefix(&self) -> [u8; 2];
 
     /// Returns the Bech32-encoded human-readable prefix for TEX addresses, for the

pczt/CHANGELOG.md

@@ -7,6 +7,10 @@ and this library adheres to Rust's notion of
 
 ## [Unreleased]
 
+## [0.2.1] - 2025-03-04
+
+Documentation improvements and rendering fix; no code changes.
+
 ## [0.2.0] - 2025-02-21
 
 ### Added

pczt/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pczt"
-version = "0.2.0"
+version = "0.2.1"
 authors = ["Jack Grigg <jack@electriccoin.co>"]
 edition.workspace = true
 rust-version.workspace = true
@@ -10,6 +10,10 @@ repository.workspace = true
 license.workspace = true
 categories.workspace = true
 
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
 [dependencies]
 zcash_note_encryption = { workspace = true, optional = true }
 zcash_primitives = { workspace = true, optional = true }
@@ -40,8 +44,13 @@ nonempty = { workspace = true, optional = true }
 orchard = { workspace = true, optional = true }
 pasta_curves = { workspace = true, optional = true }
 
-# - Bolierplate
-getset = "0.1"
+# Dependencies used internally:
+# (Breaking upgrades to these are usually backwards-compatible, but check MSRVs.)
+# - Boilerplate
+getset.workspace = true
+
+# - Documentation
+document-features = { workspace = true, optional = true }
 
 [dev-dependencies]
 incrementalmerkletree.workspace = true
@@ -55,13 +64,19 @@ zcash_proofs = { workspace = true, features = ["bundled-prover"] }
 zip32.workspace = true
 
 [features]
+default = ["std"]
+std = ["document-features"]
+
+## Enables functionality that requires Orchard protocol types.
 orchard = [
     "dep:ff",
     "dep:nonempty",
     "dep:orchard",
     "dep:pasta_curves",
     "dep:zcash_protocol",
 ]
+
+## Enables functionality that requires Sapling protocol types.
 sapling = [
     "dep:bls12_381",
     "dep:ff",
@@ -71,10 +86,25 @@ sapling = [
     "dep:zcash_note_encryption",
     "dep:zcash_protocol",
 ]
+
+## Enables functionality that requires Zcash transparent protocol types.
 transparent = ["dep:secp256k1", "dep:transparent", "dep:zcash_protocol"]
+
+## Enables building a PCZT from the output of `zcash_primitives`'s `Builder::build_for_pczt`.
 zcp-builder = ["dep:zcash_primitives", "dep:zcash_protocol"]
+
+#! ### PCZT roles behind feature flags
+#!
+#! These roles require awareness of at least one payment protocol's types in order to
+#! function.
+
+## Enables the I/O Finalizer role.
 io-finalizer = ["dep:zcash_primitives", "orchard", "sapling", "transparent"]
+
+## Enables the Prover role.
 prover = ["dep:rand_core", "sapling?/temporary-zcashd"]
+
+## Enables the Signer role.
 signer = [
     "dep:blake2b_simd",
     "dep:rand_core",
@@ -83,7 +113,11 @@ signer = [
     "sapling",
     "transparent",
 ]
+
+## Enables the Spend Finalizer role.
 spend-finalizer = ["transparent"]
+
+## Enables the Transaction Extractor role.
 tx-extractor = [
     "dep:rand_core",
     "dep:zcash_primitives",

pczt/README.md

@@ -1,6 +1,13 @@
 # pczt
 
-TBD
+This library implements the Partially Created Zcash Transaction (PCZT) format.
+This format enables splitting up the logical steps of creating a Zcash transaction
+across distinct entities. The entity roles roughly match those specified in
+[BIP 174: Partially Signed Bitcoin Transaction Format] and [BIP 370: PSBT Version 2],
+with additional Zcash-specific roles.
+
+[BIP 174: Partially Signed Bitcoin Transaction Format]: https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki
+[BIP 370: PSBT Version 2]: https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki
 
 ## License
 

pczt/src/common.rs

@@ -1,3 +1,5 @@
+//! The common fields of a PCZT.
+
 use alloc::collections::BTreeMap;
 use alloc::string::String;
 use alloc::vec::Vec;

pczt/src/lib.rs

@@ -1,52 +1,22 @@
 //! The Partially Created Zcash Transaction (PCZT) format.
 //!
-//! Goal is to split up the parts of creating a transaction across distinct entities.
-//! The entity roles roughly match BIP 174: Partially Signed Bitcoin Transaction Format.
-//! - Creator (single entity)
-//!   - Creates the base PCZT with no information about spends or outputs.
-//! - Constructor (anyone can contribute)
-//!   - Adds spends and outputs to the PCZT.
-//!   - Before any input or output may be added, the constructor must check the
-//!     `Global.tx_modifiable` field. Inputs may only be added if the Inputs Modifiable
-//!     flag is True. Outputs may only be added if the Outputs Modifiable flag is True.
-//!   - A single entity is likely to be both a Creator and Constructor.
-//! - IO Finalizer (anyone can execute)
-//!   - Sets the appropriate bits in `Global.tx_modifiable` to 0.
-//!   - Updates the various bsk values using the rcv information from spends and outputs.
-//! - Updater (anyone can contribute)
-//!   - Adds information necessary for subsequent entities to proceed, such as key paths
-//!     for signing spends.
-//! - Redactor (anyone can execute)
-//!   - Removes information that is unnecessary for subsequent entities to proceed.
-//!   - This can be useful e.g. when creating a transaction that has inputs from multiple
-//!     independent Signers; each can receive a PCZT with just the information they need
-//!     to sign, but (e.g.) not the `alpha` values for other Signers.
-//! - Prover (capability holders can contribute)
-//!   - Needs all private information for a single spend or output.
-//!   - In practice, the Updater that adds a given spend or output will either act as
-//!     the Prover themselves, or add the necessary data, offload to the Prover, and
-//!     then receive back the PCZT with private data stripped and proof added.
-//! - Signer (capability holders can contribute)
-//!   - Needs the spend authorization randomizers to create signatures.
-//!   - Needs sufficient information to verify that the proof is over the correct data,
-//!     without needing to verify the proof itself.
-//!   - A Signer should only need to implement:
-//!     - Pedersen commitments using Jubjub / Pallas arithmetic (for note and value
-//!       commitments)
-//!     - BLAKE2b and BLAKE2s (and the various PRFs / CRHs they are used in)
-//!     - Nullifier check (using Jubjub / Pallas arithmetic)
-//!     - KDF plus note decryption (AEAD_CHACHA20_POLY1305)
-//!     - SignatureHash algorithm
-//!     - Signatures (RedJubjub / RedPallas)
-//!     - A source of randomness.
-//! - Combiner (anyone can execute)
-//!   - Combines several PCZTs that represent the same transaction into a single PCZT.
-//! - Spend Finalizer (anyone can execute)
-//!   - Combines partial transparent signatures into `script_sig`s.
-//! - Transaction Extractor (anyone can execute)
-//!   - Creates bindingSig and extracts the final transaction.
+//! This format enables splitting up the logical steps of creating a Zcash transaction
+//! across distinct entities. The entity roles roughly match those specified in
+//! [BIP 174: Partially Signed Bitcoin Transaction Format] and [BIP 370: PSBT Version 2],
+//! with additional Zcash-specific roles.
+//!
+//! [BIP 174: Partially Signed Bitcoin Transaction Format]: https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki
+//! [BIP 370: PSBT Version 2]: https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki
+//!
+#![cfg_attr(feature = "std", doc = "## Feature flags")]
+#![cfg_attr(feature = "std", doc = document_features::document_features!())]
+//!
 
 #![no_std]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+// Catch documentation errors caused by code changes.
+#![deny(rustdoc::broken_intra_doc_links)]
 
 #[macro_use]
 extern crate alloc;