docs(electrum): enhance API docs for fetch_prev_txouts argument

diff --git a/crates/electrum/src/bdk_electrum_client.rs b/crates/electrum/src/bdk_electrum_client.rs
index 93c9dea74ab84b1c5e72dba1e8239afc1961f146..9dfbdab7330e353dc329ebbcfa260b8b8d1c3534 100644 (file)
--- a/crates/electrum/src/bdk_electrum_client.rs
+++ b/crates/electrum/src/bdk_electrum_client.rs
@@ -108,12 +108,22 @@ impl<E: ElectrumApi> BdkElectrumClient<E> {
     /// returns updates for [`bdk_chain`] data structures.
     ///
     /// - `request`: struct with data required to perform a spk-based blockchain client full scan,
-    ///              see [`FullScanRequest`]
+    ///              see [`FullScanRequest`].
     /// - `stop_gap`: the full scan for each keychain stops after a gap of script pubkeys with no
-    ///              associated transactions
+    ///               associated transactions.
     /// - `batch_size`: specifies the max number of script pubkeys to request for in a single batch
-    ///              request
-    /// - `fetch_prev_txouts`: specifies whether or not we want previous `TxOut`s for fee
+    ///                 request.
+    /// - `fetch_prev_txouts`: specifies whether we want previous `TxOut`s for fee calculation.
+    ///                        Note that this requires additional calls to the Electrum server, but
+    ///                        is necessary for calculating the fee on a transaction if your wallet
+    ///                        does not own the inputs. Methods like [`Wallet.calculate_fee`] and
+    ///                        [`Wallet.calculate_fee_rate`] will return a
+    ///                        [`CalculateFeeError::MissingTxOut`] error if those `TxOut`s are not
+    ///                        present in the transaction graph.
+    ///
+    /// [`CalculateFeeError::MissingTxOut`]: bdk_chain::tx_graph::CalculateFeeError::MissingTxOut
+    /// [`Wallet.calculate_fee`]: https://docs.rs/bdk_wallet/latest/bdk_wallet/struct.Wallet.html#method.calculate_fee
+    /// [`Wallet.calculate_fee_rate`]: https://docs.rs/bdk_wallet/latest/bdk_wallet/struct.Wallet.html#method.calculate_fee_rate
     pub fn full_scan<K: Ord + Clone>(
         &self,
         request: FullScanRequest<K>,
@@ -154,14 +164,22 @@ impl<E: ElectrumApi> BdkElectrumClient<E> {
     /// - `request`: struct with data required to perform a spk-based blockchain client sync,
     ///              see [`SyncRequest`]
     /// - `batch_size`: specifies the max number of script pubkeys to request for in a single batch
-    ///              request
-    /// - `fetch_prev_txouts`: specifies whether or not we want previous `TxOut`s for fee
-    ///              calculation
+    ///                 request
+    /// - `fetch_prev_txouts`: specifies whether we want previous `TxOut`s for fee calculation.
+    ///                        Note that this requires additional calls to the Electrum server, but
+    ///                        is necessary for calculating the fee on a transaction if your wallet
+    ///                        does not own the inputs. Methods like [`Wallet.calculate_fee`] and
+    ///                        [`Wallet.calculate_fee_rate`] will return a
+    ///                        [`CalculateFeeError::MissingTxOut`] error if those `TxOut`s are not
+    ///                        present in the transaction graph.
     ///
     /// If the scripts to sync are unknown, such as when restoring or importing a keychain that
     /// may include scripts that have been used, use [`full_scan`] with the keychain.
     ///
     /// [`full_scan`]: Self::full_scan
+    /// [`CalculateFeeError::MissingTxOut`]: bdk_chain::tx_graph::CalculateFeeError::MissingTxOut
+    /// [`Wallet.calculate_fee`]: https://docs.rs/bdk_wallet/latest/bdk_wallet/struct.Wallet.html#method.calculate_fee
+    /// [`Wallet.calculate_fee_rate`]: https://docs.rs/bdk_wallet/latest/bdk_wallet/struct.Wallet.html#method.calculate_fee_rate
     pub fn sync(
         &self,
         request: SyncRequest,