Documentation changes from code review

Co-authored-by: Daira-Emma Hopwood <[email protected]>
Co-authored-by: Kris Nuttycombe <[email protected]>

src/builder.rs

@@ -265,7 +265,7 @@ impl SpendInfo {
 
     /// Builds the spend half of an action.
     ///
-    /// Defined in [Zcash Protocol Spec § 4.7.3: Sending Notes (Orchard)][orchardsend].
+    /// The returned values are chosen as in [Zcash Protocol Spec § 4.7.3: Sending Notes (Orchard)][orchardsend].
     ///
     /// [orchardsend]: https://zips.z.cash/protocol/nu5.pdf#orchardsend
     fn build(
@@ -386,7 +386,8 @@ impl OutputInfo {
             recipient: Some(self.recipient),
             value: Some(self.value),
             rseed: Some(*note.rseed()),
-            // TODO: Save this?
+            // TODO: Extract ock from the encryptor and save it so
+            // Signers can check `out_ciphertext`.
             ock: None,
             zip32_derivation: None,
             proprietary: BTreeMap::new(),

src/pczt.rs

@@ -82,6 +82,9 @@ impl Bundle {
     /// Returns a mutable reference to the actions in this bundle.
     ///
     /// This is used by Signers to apply signatures with [`Action::sign`].
+    ///
+    /// Note: updating the `Action`s via the returned slice will not update other
+    /// fields of the bundle dependent on them, such as `value_sum` and `bsk`.
     pub fn actions_mut(&mut self) -> &mut [Action] {
         &mut self.actions
     }
@@ -117,7 +120,7 @@ pub struct Action {
     pub(crate) rcv: Option<ValueCommitTrapdoor>,
 }
 
-/// Information about an Orchars spend within a transaction.
+/// Information about an Orchard spend within a transaction.
 #[derive(Debug, Getters)]
 #[getset(get = "pub")]
 pub struct Spend {