Documentation fixes from code review.

Co-authored-by: str4d <thestr4d@gmail.com>

zcash_extensions/src/consensus/transparent.rs

@@ -60,7 +60,7 @@ pub trait Epoch {
     /// For a specific epoch, if the extension ID and mode of the supplied
     /// witness matches that of the supplied precondition, these values will
     /// be passed to the associated extension for verification, along with
-    /// whatever that extension requires of the provided `Context`.
+    /// whatever that extension requires of the provided [`Context`].
     ///
     /// Successful validation is indicated by the returned Result containing
     /// no errors.
@@ -89,7 +89,7 @@ impl<'a> demo::Context for Context<'a> {
 }
 
 /// Identifier for the set of TZEs associated with the ZFUTURE network upgrade.
-/// This epoch is intended only for use on test networks.
+/// This epoch is intended only for use on private test networks.
 struct EpochVTest;
 
 impl Epoch for EpochVTest {
@@ -108,7 +108,7 @@ impl Epoch for EpochVTest {
         match ext_id {
             ExtensionId::Demo => demo::Program
                 .verify(precondition, witness, ctx)
-                .map_err(|e| Error::ProgramError(format!("Epoch v1 program error: {}", e))),
+                .map_err(|e| Error::ProgramError(format!("Epoch vTest program error: {}", e))),
         }
     }
 }

zcash_primitives/src/extensions/transparent.rs

@@ -5,9 +5,8 @@ use std::fmt;
 
 /// Binary parsing capability for TZE preconditions & witnesses.
 ///
-/// Serialization formats interpreted by implementations of this
-/// trait become consensus-critical upon activation of of the
-/// extension that uses them.
+/// Serialization formats interpreted by implementations of this trait become consensus-critical
+/// upon activation of of the extension that uses them.
 pub trait FromPayload: Sized {
     type Error;
 
@@ -17,21 +16,19 @@ pub trait FromPayload: Sized {
 
 /// Binary serialization capability for TZE preconditions & witnesses.
 ///
-/// Serialization formats used by implementations of this
-/// trait become consensus-critical upon activation of of the
-/// extension that uses them.
+/// Serialization formats used by implementations of this trait become consensus-critical upon
+/// activation of of the extension that uses them.
 pub trait ToPayload {
     /// Returns a serialized payload and its corresponding mode.
     fn to_payload(&self) -> (u32, Vec<u8>);
 }
 
 /// A condition that can be used to encumber transparent funds.
 ///
-/// This struct is an intermediate representation between the
-/// serialized binary format which is used inside of a transaction
-/// and extension-specific types. The payload field of this struct
-/// is treated as opaque to all but extension corresponding to the
-/// encapsulated extension_id value.
+/// This struct is an intermediate representation between the serialized binary format which is
+/// used inside of a transaction, and extension-specific types. The payload field of this struct is
+/// treated as opaque to all but the extension corresponding to the encapsulated `extension_id`
+/// value.
 #[derive(Clone, Debug, PartialEq)]
 pub struct Precondition {
     pub extension_id: u32,
@@ -58,14 +55,12 @@ impl Precondition {
     }
 }
 
-/// Data that satisfies the precondition for prior encumbered funds, enabling them to be
-/// spent.
+/// Data that satisfies the precondition for prior encumbered funds, enabling them to be spent.
 ///
-/// This struct is an intermediate representation between the
-/// serialized binary format which is used inside of a transaction
-/// and extension-specific types. The payload field of this struct
-/// is treated as opaque to all but extension corresponding to the
-/// encapsulated extension_id value.
+/// This struct is an intermediate representation between the serialized binary format which is
+/// used inside of a transaction, and extension-specific types. The payload field of this struct is
+/// treated as opaque to all but the extension corresponding to the encapsulated `extension_id`
+/// value.
 #[derive(Clone, Debug, PartialEq)]
 pub struct Witness {
     pub extension_id: u32,
@@ -110,35 +105,35 @@ impl<E: fmt::Display> fmt::Display for Error<E> {
     }
 }
 
-/// This is the primary trait which must be implemented by an extension type
-/// for that type to be eligible for inclusion in Zcash consensus rules.
+/// This is the primary trait which must be implemented by an extension type for that type to be
+/// eligible for inclusion in Zcash consensus rules.
 pub trait Extension<C> {
     /// Extension-specific precondition type. The extension will need to implement
-    /// [`FromPayload<Error = Self::Error>`] for this type in order for their
-    /// extension to be eligible for integration into consensus rules.
+    /// [`FromPayload<Error = Self::Error>`] for this type in order for their extension to be
+    /// eligible for integration into consensus rules.
     type Precondition;
 
-    /// Extension-specific witness type. The extension will need to implement
-    /// [`FromPayload<Error = Self::Error>`] for this type in order for their
-    /// extension to be eligible for integration into consensus rules.
+    /// Extension-specific witness type. The extension will need to implement [`FromPayload<Error =
+    /// Self::Error>`] for this type in order for their extension to be eligible for integration
+    /// into consensus rules.
     type Witness;
 
     /// Extension-specific error type. This should encompass both parsing and verification errors.
     type Error;
 
-    /// This is the primary method that an extension must implement. Implementations should
-    /// return [`Ok(())`] if verification of the witness succeeds against the supplied
-    /// precondition, and an error in any other case.
+    /// This is the primary method that an extension must implement. Implementations should return
+    /// [`Ok(())`] if verification of the witness succeeds against the supplied precondition, and
+    /// an error in any other case.
     fn verify_inner(
         &self,
         precondition: &Self::Precondition,
         witness: &Self::Witness,
         context: &C,
     ) -> Result<(), Self::Error>;
 
-    /// This is a convenience method intended for use by consensus nodes at the integration
-    /// point to provide easy interoperation with the opaque, cross-extension
-    /// `Precondition` and `Witness` types.
+    /// This is a convenience method intended for use by consensus nodes at the integration point
+    /// to provide easy interoperation with the opaque, cross-extension `Precondition` and
+    /// `Witness` types.
     fn verify(
         &self,
         precondition: &Precondition,
@@ -157,6 +152,8 @@ pub trait Extension<C> {
     }
 }
 
+/// An interface for transaction builders which support addition of TZE inputs and outputs.
+///
 /// This extension trait is satisfied by [`transaction::builder::Builder`]. It provides a minimal
 /// contract for interacting with the transaction builder, that extension library authors can use
 /// to add extension-specific builder traits that may be used to interact with the transaction
@@ -169,15 +166,14 @@ pub trait ExtensionTxBuilder<'a> {
     type BuildCtx;
     type BuildError;
 
-    /// Add a TZE input to the transaction under construction by providing a witness
-    /// to a precondition identified by a prior outpoint.
+    /// Adds a TZE input to the transaction by providing a witness to a precondition identified by a
+    /// prior outpoint.
     ///
-    /// The `witness_builder` function allows the transaction builder to provide extra
-    /// contextual information from the transaction under construction to be used
-    /// in the production of this witness (for example, so that the witness may
-    /// internally make commitments based upon this information.) For the standard
-    /// transaction builder, the value provided here is the transaction under
-    /// construction.
+    /// The `witness_builder` function allows the transaction builder to provide extra contextual
+    /// information from the transaction under construction to be used in the production of this
+    /// witness (for example, so that the witness may internally make commitments based upon this
+    /// information.) For the standard transaction builder, the value provided here is the
+    /// transaction under construction.
     fn add_tze_input<WBuilder, W: ToPayload>(
         &mut self,
         extension_id: u32,
@@ -188,12 +184,12 @@ pub trait ExtensionTxBuilder<'a> {
     where
         WBuilder: 'a + (FnOnce(&Self::BuildCtx) -> Result<W, Self::BuildError>);
 
-    /// Add a TZE precondition to the transaction which must be satisfied by a future
-    /// transaction's witness in order to spend the specified amount.
-    fn add_tze_output<P: ToPayload>(
+    /// Adds a TZE precondition to the transaction which must be satisfied by a future transaction's
+    /// witness in order to spend the specified `amount`.
+    fn add_tze_output<Precondition: ToPayload>(
         &mut self,
         extension_id: u32,
         value: Amount,
-        guarded_by: &P,
+        guarded_by: &Precondition,
     ) -> Result<(), Self::BuildError>;
 }

zcash_primitives/src/transaction/builder.rs

@@ -788,7 +788,7 @@ impl<'a, P: consensus::Parameters, R: RngCore + CryptoRng> Builder<'a, P, R> {
             None
         };
 
-        // // Create TZE input witnesses
+        // Create TZE input witnesses
         for (i, tze_in) in self.tze_inputs.builders.into_iter().enumerate() {
             // Need to enable witness to commit to the amount.
             // - So hardware wallets "know" the amount without having to be sent all the