From fc3afc6d8082d35acd1ba61b80e8b3b6a39e5fb9 Mon Sep 17 00:00:00 2001
From: Armin Sabouri <armins88@gmail.com>
Date: Mon, 25 Nov 2024 13:06:14 -0500
Subject: [PATCH] chore(send): additional function docs

---
 payjoin/src/send/mod.rs | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/payjoin/src/send/mod.rs b/payjoin/src/send/mod.rs
index f31bb6f0..8738edfb 100644
--- a/payjoin/src/send/mod.rs
+++ b/payjoin/src/send/mod.rs
@@ -235,11 +235,16 @@ impl<'a> SenderBuilder<'a> {
 #[derive(Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "v2", derive(Serialize, Deserialize))]
 pub struct Sender {
+    /// The original PSBT.
     psbt: Psbt,
+    /// The endpoint to send the request to. This is either a pj directory (BIP78) or a receiver's endpoint (BIP77).
     endpoint: Url,
+    /// Disallow reciever to substitute original outputs.
     disable_output_substitution: bool,
+    /// (maxadditionalfeecontribution, additionalfeeoutputindex)
     fee_contribution: Option<(bitcoin::Amount, usize)>,
     min_fee_rate: FeeRate,
+    /// Script of the person being paid
     payee: ScriptBuf,
 }
 
@@ -350,6 +355,7 @@ impl V1Context {
 
 #[cfg(feature = "v2")]
 pub struct V2PostContext {
+    /// The endpoint to send the request to. This is either a pj directory or a receiver's endpoint.
     endpoint: Url,
     psbt_ctx: PsbtContext,
     hpke_ctx: HpkeContext,
@@ -383,6 +389,7 @@ impl V2PostContext {
 #[cfg(feature = "v2")]
 #[derive(Debug, Clone)]
 pub struct V2GetContext {
+    /// This is either the pj directory or the receiver's endpoint
     endpoint: Url,
     psbt_ctx: PsbtContext,
     hpke_ctx: HpkeContext,
@@ -558,7 +565,7 @@ impl PsbtContext {
         Ok(())
     }
 
-    // version and lock time
+    /// Check that the version and lock time are the same as in the original PSBT.
     fn basic_checks(&self, proposal: &Psbt) -> InternalResult<()> {
         check_eq!(
             proposal.unsigned_tx.version,
@@ -638,9 +645,9 @@ impl PsbtContext {
         Ok(())
     }
 
-    // Restore Original PSBT utxos that the receiver stripped.
-    // The BIP78 spec requires utxo information to be removed, but many wallets
-    // require it to be present to sign.
+    /// Restore Original PSBT utxos that the receiver stripped.
+    /// The BIP78 spec requires utxo information to be removed, but many wallets
+    /// require it to be present to sign.
     fn restore_original_utxos(&self, proposal: &mut Psbt) -> InternalResult<()> {
         let mut original_inputs = self.original_psbt.input_pairs().peekable();
         let proposal_inputs =
@@ -714,6 +721,8 @@ impl PsbtContext {
     }
 }
 
+/// Ensure that the payee output spk is found the list of outputs only once.
+/// And that the amount is the same as in the original PSBT.
 fn check_single_payee(
     psbt: &Psbt,
     script_pubkey: &Script,
@@ -763,6 +772,7 @@ fn clear_unneeded_fields(psbt: &mut Psbt) {
     }
 }
 
+/// Check that the output contributing to the fee is not less than the fee.
 fn check_fee_output_amount(
     output: &TxOut,
     fee: bitcoin::Amount,
@@ -779,6 +789,9 @@ fn check_fee_output_amount(
     }
 }
 
+/// Find the sender's change output.
+/// The first output should always be the payee spk.
+/// If the fee contribution is clamped, any non-payee spk can be the change output.
 fn find_change_index(
     psbt: &Psbt,
     payee: &Script,
@@ -805,6 +818,9 @@ fn find_change_index(
     Ok(Some((check_fee_output_amount(output, fee, clamp_fee_contribution)?, index)))
 }
 
+/// Checks that the change output index is valid
+/// and that the amount is not less than the fee we are suppose to
+/// be contributing.
 fn check_change_index(
     psbt: &Psbt,
     payee: &Script,