From 4f702ebf1edc964ca2cc3b2c5144149fd63b76f5 Mon Sep 17 00:00:00 2001
From: thunderbiscuit <thunderbiscuit@protonmail.com>
Date: Mon, 25 Nov 2024 15:23:42 -0500
Subject: [PATCH] docs: add docstrings for BumpFeeTxBuilder

---
 bdk-ffi/src/bdk.udl | 39 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 37 insertions(+), 2 deletions(-)

diff --git a/bdk-ffi/src/bdk.udl b/bdk-ffi/src/bdk.udl
index b126c195..44eb2723 100644
--- a/bdk-ffi/src/bdk.udl
+++ b/bdk-ffi/src/bdk.udl
@@ -676,8 +676,8 @@ dictionary Condition {
   LockTime? timelock;
 };
 
-/// A `TxBuilder` is created by calling `build_tx` or `build_fee_bump` on a wallet. After assigning it, you set options on it
-/// until finally calling `finish` to consume the builder and generate the transaction.
+/// A `TxBuilder` is created by calling `build_tx` on a wallet. After assigning it, you set options on it until finally
+/// calling `finish` to consume the builder and generate the transaction.
 interface TxBuilder {
   constructor();
 
@@ -817,19 +817,54 @@ interface TxBuilder {
   Psbt finish([ByRef] Wallet wallet);
 };
 
+/// A `BumpFeeTxBuilder` is created by calling `build_fee_bump` on a wallet. After assigning it, you set options on it
+/// until finally calling `finish` to consume the builder and generate the transaction.
 interface BumpFeeTxBuilder {
   constructor(string txid, FeeRate fee_rate);
 
+  /// Set an exact `nSequence` value.
+  ///
+  /// This can cause conflicts if the wallet’s descriptors contain an "older" (`OP_CSV`) operator and the given
+  /// `nsequence` is lower than the CSV value.
   BumpFeeTxBuilder set_exact_sequence(u32 nsequence);
 
+  /// Set the current blockchain height.
+  ///
+  /// This will be used to:
+  ///
+  /// 1. Set the `nLockTime` for preventing fee sniping. Note: This will be ignored if you manually specify a
+  /// `nlocktime` using `TxBuilder::nlocktime`.
+  ///
+  /// 2. Decide whether coinbase outputs are mature or not. If the coinbase outputs are not mature at `current_height`,
+  /// we ignore them in the coin selection. If you want to create a transaction that spends immature coinbase inputs,
+  /// manually add them using `TxBuilder::add_utxos`.
+  /// In both cases, if you don’t provide a current height, we use the last sync height.
   BumpFeeTxBuilder current_height(u32 height);
 
+  /// Use a specific nLockTime while creating the transaction.
+  ///
+  /// This can cause conflicts if the wallet’s descriptors contain an "after" (`OP_CLTV`) operator.
   BumpFeeTxBuilder nlocktime(LockTime locktime);
 
+  /// Set whether or not the dust limit is checked.
+  ///
+  /// Note: by avoiding a dust limit check you may end up with a transaction that is non-standard.
   BumpFeeTxBuilder allow_dust(boolean allow_dust);
 
+  /// Build a transaction with a specific version.
+  ///
+  /// The version should always be greater than 0 and greater than 1 if the wallet’s descriptors contain an "older"
+  /// (`OP_CSV`) operator.
   BumpFeeTxBuilder version(i32 version);
 
+  /// Finish building the transaction.
+  ///
+  /// Uses the thread-local random number generator (rng).
+  ///
+  /// Returns a new `Psbt` per BIP174.
+  ///
+  /// WARNING: To avoid change address reuse you must persist the changes resulting from one or more calls to this
+  /// method before closing the wallet. See `Wallet::reveal_next_address`.
   [Throws=CreateTxError]
   Psbt finish([ByRef] Wallet wallet);
 };