Documentation fixes in zcash_client_backend.

zcash_client_backend/src/data_api.rs

@@ -187,11 +187,21 @@ pub struct PrunedBlock<'a> {
     pub transactions: &'a Vec<WalletTx<Nullifier>>,
 }
 
+/// A transaction that was detected during scanning of the blockchain,
+/// including its decrypted Sapling outputs.
+///
+/// The purpose of this struct is to permit atomic updates of the
+/// wallet database when transactions are successfully decrypted.
 pub struct ReceivedTransaction<'a> {
     pub tx: &'a Transaction,
     pub outputs: &'a Vec<DecryptedOutput>,
 }
 
+/// A transaction that was constructed and sent by the wallet.
+///
+/// The purpose of this struct is to permit atomic updates of the
+/// wallet database when transactions are created and submitted
+/// to the network.
 pub struct SentTransaction<'a> {
     pub tx: &'a Transaction,
     pub created: time::OffsetDateTime,

zcash_client_backend/src/encoding.rs

@@ -1,9 +1,9 @@
 //! Encoding and decoding functions for Zcash key and address structs.
 //!
-//! Human-Readable Prefixes (HRPs) for Bech32 encodings are located in the [`zcash_primitives::constants`]
-//! module.
+//! Human-Readable Prefixes (HRPs) for Bech32 encodings are located in the
+//! [zcash_primitives::constants][constants] module.
 //!
-//! [`constants`]: zcash_primitives::constants
+//! [constants]: zcash_primitives::constants
 
 use bech32::{self, Error, FromBase32, ToBase32};
 use bs58::{self, decode::Error as Bs58Error};
@@ -52,11 +52,14 @@ where
 /// let extsk = spending_key(&[0; 32][..], COIN_TYPE, 0);
 /// let encoded = encode_extended_spending_key(HRP_SAPLING_EXTENDED_SPENDING_KEY, &extsk);
 /// ```
+/// [`ExtendedSpendingKey`]: zcash_primitives::zip32::ExtendedSpendingKey
 pub fn encode_extended_spending_key(hrp: &str, extsk: &ExtendedSpendingKey) -> String {
     bech32_encode(hrp, |w| extsk.write(w))
 }
 
 /// Decodes an [`ExtendedSpendingKey`] from a Bech32-encoded string.
+///
+/// [`ExtendedSpendingKey`]: zcash_primitives::zip32::ExtendedSpendingKey
 pub fn decode_extended_spending_key(
     hrp: &str,
     s: &str,
@@ -82,11 +85,14 @@ pub fn decode_extended_spending_key(
 /// let extfvk = ExtendedFullViewingKey::from(&extsk);
 /// let encoded = encode_extended_full_viewing_key(HRP_SAPLING_EXTENDED_FULL_VIEWING_KEY, &extfvk);
 /// ```
+/// [`ExtendedFullViewingKey`]: zcash_primitives::zip32::ExtendedFullViewingKey
 pub fn encode_extended_full_viewing_key(hrp: &str, extfvk: &ExtendedFullViewingKey) -> String {
     bech32_encode(hrp, |w| extfvk.write(w))
 }
 
 /// Decodes an [`ExtendedFullViewingKey`] from a Bech32-encoded string.
+///
+/// [`ExtendedFullViewingKey`]: zcash_primitives::zip32::ExtendedFullViewingKey
 pub fn decode_extended_full_viewing_key(
     hrp: &str,
     s: &str,
@@ -127,6 +133,7 @@ pub fn decode_extended_full_viewing_key(
 ///     "ztestsapling1qqqqqqqqqqqqqqqqqqcguyvaw2vjk4sdyeg0lc970u659lvhqq7t0np6hlup5lusxle75ss7jnk",
 /// );
 /// ```
+/// [`PaymentAddress`]: zcash_primitives::primitives::PaymentAddress
 pub fn encode_payment_address(hrp: &str, addr: &PaymentAddress) -> String {
     bech32_encode(hrp, |w| w.write_all(&addr.to_bytes()))
 }
@@ -167,6 +174,7 @@ pub fn encode_payment_address(hrp: &str, addr: &PaymentAddress) -> String {
 ///     Ok(Some(pa)),
 /// );
 /// ```
+/// [`PaymentAddress`]: zcash_primitives::primitives::PaymentAddress
 pub fn decode_payment_address(hrp: &str, s: &str) -> Result<Option<PaymentAddress>, Error> {
     bech32_decode(hrp, s, |data| {
         if data.len() != 43 {
@@ -210,6 +218,7 @@ pub fn decode_payment_address(hrp: &str, s: &str) -> Result<Option<PaymentAddres
 ///     "t26YoyZ1iPgiMEWL4zGUm74eVWfhyDMXzY2",
 /// );
 /// ```
+/// [`TransparentAddress`]: zcash_primitives::legacy::TransparentAddress
 pub fn encode_transparent_address(
     pubkey_version: &[u8],
     script_version: &[u8],
@@ -263,6 +272,7 @@ pub fn encode_transparent_address(
 ///     Ok(Some(TransparentAddress::Script([0; 20]))),
 /// );
 /// ```
+/// [`TransparentAddress`]: zcash_primitives::legacy::TransparentAddress
 pub fn decode_transparent_address(
     pubkey_version: &[u8],
     script_version: &[u8],

zcash_client_backend/src/keys.rs

@@ -17,6 +17,7 @@ use zcash_primitives::zip32::{ChildIndex, ExtendedSpendingKey};
 ///
 /// let extsk = spending_key(&[0; 32][..], COIN_TYPE, 0);
 /// ```
+/// [`ExtendedSpendingKey`]: zcash_primitives::zip32::ExtendedSpendingKey
 pub fn spending_key(seed: &[u8], coin_type: u32, account: u32) -> ExtendedSpendingKey {
     if seed.len() < 32 {
         panic!("ZIP 32 seeds MUST be at least 32 bytes");

zcash_client_backend/src/wallet.rs

@@ -63,6 +63,8 @@ pub struct WalletShieldedOutput<N> {
     pub nf: N,
 }
 
+/// Information about a note that is tracked by the wallet that is available for spending,
+/// with sufficient information for use in note selection.
 pub struct SpendableNote {
     pub diversifier: Diversifier,
     pub note_value: Amount,

zcash_client_backend/src/welding_rig.rs

@@ -23,6 +23,8 @@ use crate::wallet::{AccountId, WalletShieldedOutput, WalletShieldedSpend, Wallet
 ///
 /// The given [`CommitmentTree`] and existing [`IncrementalWitness`]es are incremented
 /// with this output's commitment.
+///
+/// [`ScanningKey`]: zcash_client_backend::welding_rig::ScanningKey
 #[allow(clippy::too_many_arguments)]
 fn scan_output<P: consensus::Parameters, K: ScanningKey>(
     params: &P,
@@ -88,10 +90,23 @@ fn scan_output<P: consensus::Parameters, K: ScanningKey>(
 /// A key that can be used to perform trial decryption and nullifier
 /// computation for a Sapling [`CompactOutput`]
 ///
+/// The purpose of this trait is to enable [`scan_block`]
+/// and related methods to be used with either incoming viewing keys
+/// or full viewing keys, with the data returned from trial decryption
+/// being dependent upon the type of key used. In the case that an
+/// incoming viewing key is used, only the note and payment address
+/// will be returned; in the case of a full viewing key, the
+/// nullifier for the note can also be obtained.
+///
 /// [`CompactOutput`]: crate::proto::compact_formats::CompactOutput
+/// [`scan_block`]: crate::welding_rig::scan_block
 pub trait ScanningKey {
+    /// The type of nullifier extracted when a note is successfully
+    /// obtained by trial decryption.
     type Nf;
 
+    /// Attempt to decrypt a Sapling note and payment address
+    /// from the specified ciphertext using this scanning key.
     fn try_decryption<P: consensus::Parameters>(
         &self,
         params: &P,
@@ -101,9 +116,17 @@ pub trait ScanningKey {
         ct: &[u8],
     ) -> Option<(Note, PaymentAddress)>;
 
+    /// Produce the nullifier for the specified note and witness, if possible.
+    /// IVK-based implementations of this trait cannot successfully derive
+    /// nullifiers, in which case `Self::Nf` should be set to the unit type
+    /// and this function is a no-op.
     fn nf(&self, note: &Note, witness: &IncrementalWitness<Node>) -> Self::Nf;
 }
 
+/// The [`ScanningKey`] implementation for [`ExtendedFullViewingKey`]s.
+/// Nullifiers may be derived when scanning with these keys.
+///
+/// [`ExtendedFullViewingKey`]: zcash_primitives::zip32::ExtendedFullViewingKey
 impl ScanningKey for ExtendedFullViewingKey {
     type Nf = Nullifier;
 
@@ -123,6 +146,10 @@ impl ScanningKey for ExtendedFullViewingKey {
     }
 }
 
+/// The [`ScanningKey`] implementation for [`SaplingIvk`]s.
+/// Nullifiers cannot be derived when scanning with these keys.
+///
+/// [`SaplingIvk`]: zcash_primitives::primitives::SaplingIvk
 impl ScanningKey for SaplingIvk {
     type Nf = ();
 
@@ -158,10 +185,11 @@ impl ScanningKey for SaplingIvk {
 /// [`ExtendedFullViewingKey`]: zcash_primitives::zip32::ExtendedFullViewingKey
 /// [`SaplingIvk`]: zcash_primitives::primitives::SaplingIvk
 /// [`CompactBlock`]: crate::proto::compact_formats::CompactBlock
-/// [`ScanningKey`]: self::ScanningKey
+/// [`ScanningKey`]: zcash_client_backend::welding_rig::ScanningKey
 /// [`CommitmentTree`]: zcash_primitives::merkle_tree::CommitmentTree
 /// [`IncrementalWitness`]: zcash_primitives::merkle_tree::IncrementalWitness
 /// [`WalletShieldedOutput`]: crate::wallet::WalletShieldedOutput
+/// [`WalletTx`]: crate::wallet::WalletTx
 pub fn scan_block<P: consensus::Parameters, K: ScanningKey>(
     params: &P,
     block: CompactBlock,