Merge #1494: Add documentation for Electrum's full_scan/sync

7b5657e docs(electrum): enhance API docs for fetch_prev_txouts argument (thunderbiscuit)

Pull request description:

  This PR also serves as an issue; it can't really be merged as is. I just didn't want to open an issue and just ask for better docs and instead decided to open a PR with some unfinished new API docs.

  I am working on a page for the Book of BDK that focuses on bdk_wallet + bdk_electrum syncing. A few things have been unclear to me, and I think slight additions to the API docs would fix that for others.

  ~~1. I was wondering what exactly this `confirmation_time` field on the `bdk_chain::ConfirmationTimeHeightAnchor` type represents. After digging into it (at least for the electrum client), it represents the timestamp specified by the block header where the tx was confirmed. _Question: I'd like to confirm that this always the case, e.g. that this is the timestamp used in cases where your client is an Esplora or bitcoind RPC node?_ If so, my addition to the sentence will make sense and is ready to go.~~ Edit: this is no longer a type after the rebase.
  2. I think it'd be great to add context to the `fetch_prev_txouts` argument on the full_scan and sync methods on the `BdkElectrumClient`. It says that this is necessary for "fee calculation". What does that mean? I assume it means "for calculating the fee rate on the given transactions"? (let me know if that's wrong). Even so, I'm left wondering what happens if I don't fetch them. Will my fee calculations be just plain wrong? Or will they be unavailable? A bit more context for the caller of the method would be great here. If someone knows the definite answer to this let me know and feel free to propose a doc line and I'll amend the commit!

  ### Checklists
  * [x] I've signed all my commits
  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)
  * [x] I ran `cargo fmt` and `cargo clippy` before committing

ACKs for top commit:
  evanlinjin:
    re-ACK 7b5657e

Tree-SHA512: f0ac9ae4a116c9a3f5006d6a41f626ac36c3f8495204a9eaa06d2c8003cabe0005be33fcc810028d314c505c3385a5facd2bedb3b2218ddf272b0fa2220abd39

Author: evanlinjin

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,