docs(wallet): update docs for calculate_fee/fee_rate and add_foreign_utxo

Author: notmandatory

crates/bdk/src/wallet/mod.rs

@@ -431,10 +431,17 @@ impl<D> Wallet<D> {
             .next()
     }
 
-    /// Inserts the given foreign `TxOut` at `OutPoint` into the wallet's transaction graph. Any
-    /// inserted foreign TxOuts are not persisted until [`Self::commit`] is called.
+    /// Inserts a [`TxOut`] at [`OutPoint`] into the wallet's transaction graph.
+    /// Any inserted TxOuts are not persisted until [`commit`] is called.
+    ///
+    /// This can be used to add a `TxOut` that the wallet doesn't own but is used as an input to
+    /// a [`Transaction`] passed to the [`calculate_fee`] or [`calculate_fee_rate`] functions.
     ///
     /// Only insert TxOuts you trust the values for!
+    ///
+    /// [`calculate_fee`]: Self::calculate_fee
+    /// [`calculate_fee_rate`]: Self::calculate_fee_rate
+    /// [`commit`]: Self::commit
     pub fn insert_txout(&mut self, outpoint: OutPoint, txout: TxOut)
     where
         D: PersistBackend<ChangeSet>,
@@ -445,9 +452,8 @@ impl<D> Wallet<D> {
 
     /// Calculates the fee of a given transaction. Returns 0 if `tx` is a coinbase transaction.
     ///
-    /// To calculate the fee for a [`Transaction`] that depends on foreign [`TxOut`] values you must
-    /// first manually insert the foreign TxOuts into the tx graph using the [`insert_txout`] function.
-    /// Only insert TxOuts you trust the values for!
+    /// To calculate the fee for a [`Transaction`] with inputs not owned by this wallet you must
+    /// manually insert the TxOut(s) into the tx graph using the [`insert_txout`] function.
     ///
     /// Note `tx` does not have to be in the graph for this to work.
     ///
@@ -458,9 +464,8 @@ impl<D> Wallet<D> {
 
     /// Calculate the [`FeeRate`] for a given transaction.
     ///
-    /// To calculate the fee rate for a [`Transaction`] that depends on foreign [`TxOut`] values you
-    /// must first manually insert the foreign TxOuts into the tx graph using the [`insert_txout`] function.
-    /// Only insert TxOuts you trust the values for!
+    /// To calculate the fee rate for a [`Transaction`] with inputs not owned by this wallet you must
+    /// manually insert the TxOut(s) into the tx graph using the [`insert_txout`] function.
     ///
     /// Note `tx` does not have to be in the graph for this to work.
     ///
@@ -1073,6 +1078,8 @@ impl<D> Wallet<D> {
     /// *replace by fee* (RBF). If the transaction can be fee bumped then it returns a [`TxBuilder`]
     /// pre-populated with the inputs and outputs of the original transaction.
     ///
+    ///
+    ///
     /// ## Example
     ///
     /// ```no_run

crates/bdk/src/wallet/tx_builder.rs

@@ -335,6 +335,10 @@ impl<'a, D, Cs: CoinSelectionAlgorithm, Ctx: TxBuilderContext> TxBuilder<'a, D,
     ///
     /// This is an **EXPERIMENTAL** feature, API and other major changes are expected.
     ///
+    /// In order to use [`Wallet::calculate_fee`] or [`Wallet::calculate_fee_rate`] for a transaction
+    /// created with foreign UTXO(s) you must manually insert the corresponding TxOut(s) into the tx
+    /// graph using the [`Wallet::insert_txout`] function.
+    ///
     /// # Errors
     ///
     /// This method returns errors in the following circumstances: