Miscellaneous documentation improvements.

Signed-off-by: Daira-Emma Hopwood <daira@jacaranda.org>

zcash_client_backend/src/data_api.rs

@@ -1514,8 +1514,11 @@ pub trait WalletWrite: WalletRead {
         received_tx: DecryptedTransaction<Self::AccountId>,
     ) -> Result<(), Self::Error>;
 
-    /// Saves information about a transaction that was constructed and sent by the wallet to the
+    /// Saves information about a transaction constructed by the wallet to the persistent
-    /// persistent wallet store.
+    /// wallet store.
+    ///
+    /// The name `store_sent_tx` is somewhat misleading; this must be called *before* the
+    /// transaction is sent to the network.
     fn store_sent_tx(
         &mut self,
         sent_tx: &SentTransaction<Self::AccountId>,

zcash_client_backend/src/data_api/error.rs

@@ -85,6 +85,8 @@ pub enum Error<DataSourceError, CommitmentTreeError, SelectionError, FeeError> {
     /// An error occurred parsing the address from a payment request.
     Address(ConversionError<&'static str>),
 
+    /// The address associated with a record being inserted was not recognized as
+    /// belonging to the wallet.
     #[cfg(feature = "transparent-inputs")]
     AddressNotRecognized(TransparentAddress),
 }

zcash_client_backend/src/fees.rs

@@ -250,20 +250,20 @@ impl<NoteRefT> From<BalanceError> for ChangeError<BalanceError, NoteRefT> {
     }
 }
 
-/// An enumeration of actions to tak when a transaction would potentially create dust
+/// An enumeration of actions to take when a transaction would potentially create dust
-/// outputs (outputs that are likely to be without economic value due to fee rules.)
+/// outputs (outputs that are likely to be without economic value due to fee rules).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum DustAction {
     /// Do not allow creation of dust outputs; instead, require that additional inputs be provided.
     Reject,
     /// Explicitly allow the creation of dust change amounts greater than the specified value.
     AllowDustChange,
-    /// Allow dust amounts to be added to the transaction fee
+    /// Allow dust amounts to be added to the transaction fee.
     AddDustToFee,
 }
 
 /// A policy describing how a [`ChangeStrategy`] should treat potentially dust-valued change
-/// outputs (outputs that are likely to be without economic value due to fee rules.)
+/// outputs (outputs that are likely to be without economic value due to fee rules).
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct DustOutputPolicy {
     action: DustAction,
@@ -275,7 +275,7 @@ impl DustOutputPolicy {
     ///
     /// A dust policy created with `None` as the dust threshold will delegate determination
     /// of the dust threshold to the change strategy that is evaluating the strategy; this
-    /// recommended, but an explicit value (including zero) may be provided to explicitly
+    /// is recommended, but an explicit value (including zero) may be provided to explicitly
     /// override the determination of the change strategy.
     pub fn new(action: DustAction, dust_threshold: Option<NonNegativeAmount>) -> Self {
         Self {
@@ -284,7 +284,7 @@ impl DustOutputPolicy {
         }
     }
 
-    /// Returns the action to take in the event that a dust change amount would be produced
+    /// Returns the action to take in the event that a dust change amount would be produced.
     pub fn action(&self) -> DustAction {
         self.action
     }

zcash_client_backend/src/proto.rs

@@ -1,4 +1,4 @@
-//! Generated code for handling light client protobuf structs.
+//! This module contains generated code for handling light client protobuf structs.
 
 use incrementalmerkletree::frontier::CommitmentTree;
 use nonempty::NonEmpty;

zcash_client_sqlite/src/error.rs

@@ -89,7 +89,7 @@ pub enum SqliteClientError {
     AccountIdOutOfRange,
 
     /// The address associated with a record being inserted was not recognized as
-    /// belonging to the wallet
+    /// belonging to the wallet.
     #[cfg(feature = "transparent-inputs")]
     AddressNotRecognized(TransparentAddress),
 

zcash_keys/src/address.rs

@@ -297,7 +297,7 @@ pub enum Address {
     #[cfg(feature = "sapling")]
     Sapling(PaymentAddress),
 
-    /// A transparent address corresponding to either a public key or a `Script`.
+    /// A transparent address corresponding to either a public key hash or a script hash.
     Transparent(TransparentAddress),
 
     /// A [ZIP 316] Unified Address.

zcash_primitives/src/legacy.rs

@@ -379,7 +379,7 @@ impl Shl<&[u8]> for Script {
     }
 }
 
-/// A transparent address corresponding to either a public key or a `Script`.
+/// A transparent address corresponding to either a public key hash or a script hash.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum TransparentAddress {
     PublicKeyHash([u8; 20]),

zcash_primitives/src/transaction/components/transparent.rs

@@ -96,6 +96,8 @@ pub struct OutPoint {
 }
 
 impl OutPoint {
+    /// Constructs an `OutPoint` for the output at index `n` in the transaction
+    /// with txid `hash`.
     pub fn new(hash: [u8; 32], n: u32) -> Self {
         OutPoint { hash, n }
     }
@@ -121,18 +123,20 @@ impl OutPoint {
         writer.write_u32::<LittleEndian>(self.n)
     }
 
-    /// Returns `true` if this `OutPoint` is "null" in the Bitcoin sense: it points to the
+    /// Returns `true` if this `OutPoint` is "null" in the Bitcoin sense: it has txid set to
-    /// `u32::MAX`th output of the transaction with the all-zeroes txid.
+    /// all-zeroes and output index set to `u32::MAX`.
     fn is_null(&self) -> bool {
         // From `BaseOutPoint::IsNull()` in zcashd:
         //   return (hash.IsNull() && n == (uint32_t) -1);
         self.hash == [0; 32] && self.n == u32::MAX
     }
 
+    /// Returns the output index of this `OutPoint`.
     pub fn n(&self) -> u32 {
         self.n
     }
 
+    /// Returns the txid of the transaction containing this `OutPoint`.
     pub fn hash(&self) -> &[u8; 32] {
         &self.hash
     }

zcash_primitives/src/transaction/fees/transparent.rs

@@ -25,6 +25,7 @@ pub enum InputSize {
 }
 
 impl InputSize {
+    /// An `InputSize` corresponding to the upper bound on the size of a P2PKH input used by ZIP 317.
     pub const STANDARD_P2PKH: InputSize = InputSize::Known(P2PKH_STANDARD_INPUT_SIZE);
 }
 

zcash_primitives/src/transaction/fees/zip317.rs

@@ -44,8 +44,12 @@ pub const MINIMUM_FEE: NonNegativeAmount = NonNegativeAmount::const_from_u64(10_
 /// A [`FeeRule`] implementation that implements the [ZIP 317] fee rule.
 ///
 /// This fee rule supports Orchard, Sapling, and (P2PKH only) transparent inputs.
-/// Returns an error if a coin containing a non-p2pkh script is provided as an input.
+/// Returns an error if a coin containing a non-P2PKH script is provided as an input.
-/// This fee rule may slightly overestimate fees in case where the user is attempting to spend more than ~150 transparent inputs.
+///
+/// This fee rule may slightly overestimate fees in case where the user is attempting
+/// to spend a large number of transparent inputs. This is intentional and is relied
+/// on for the correctness of transaction construction algorithms in the
+/// `zcash_client_backend` crate.
 ///
 /// [`FeeRule`]: crate::transaction::fees::FeeRule
 /// [ZIP 317]: https//zips.z.cash/zip-0317