From cf5f714bed70cd7ee09f203f55548fb2a2c478f7 Mon Sep 17 00:00:00 2001
From: Matthew <ramsden@hey.com>
Date: Thu, 31 Oct 2024 13:37:23 -0500
Subject: [PATCH] docs: wallet type docstrings

---
 bdk-ffi/src/bdk.udl | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/bdk-ffi/src/bdk.udl b/bdk-ffi/src/bdk.udl
index 44eb2723..dc88fb79 100644
--- a/bdk-ffi/src/bdk.udl
+++ b/bdk-ffi/src/bdk.udl
@@ -318,46 +318,88 @@ interface TxidParseError {
 // bdk_wallet crate - types module
 // ------------------------------------------------------------------------
 
+/// Types of keychains
 enum KeychainKind {
+  /// External keychain, used for deriving recipient addresses.
   "External",
+
+  /// Internal keychain, used for deriving change addresses.
   "Internal",
 };
 
+/// A derived address and the index it was found at.
 dictionary AddressInfo {
+  /// Child index of this address
   u32 index;
+
+  /// Address
   Address address;
+
+  /// Type of keychain
   KeychainKind keychain;
 };
 
+/// Balance, differentiated into various categories.
 dictionary Balance {
+  /// All coinbase outputs not yet matured
   Amount immature;
 
+  /// Unconfirmed UTXOs generated by a wallet tx
   Amount trusted_pending;
 
+  /// Unconfirmed UTXOs received from an external wallet
   Amount untrusted_pending;
 
+  /// Confirmed and immediately spendable balance
   Amount confirmed;
 
+  /// Get sum of trusted_pending and confirmed coins.
+  ///
+  /// This is the balance you can spend right now that shouldn't get cancelled via another party
+  /// double spending it.
   Amount trusted_spendable;
 
+  /// Get the whole balance visible to the wallet.
   Amount total;
 };
 
+/// An unspent output owned by a [`Wallet`].
 dictionary LocalOutput {
+  /// Reference to a transaction output
   OutPoint outpoint;
+
+  /// Transaction output
   TxOut txout;
+
+  /// Type of keychain
   KeychainKind keychain;
+
+  /// Whether this UTXO is spent or not
   boolean is_spent;
 };
 
+/// Bitcoin transaction output.
+///
+/// Defines new coins to be created as a result of the transaction,
+/// along with spending conditions ("script", aka "output script"),
+/// which an input spending it must satisfy.
+///
+/// An output that is not yet spent by an input is called Unspent Transaction Output ("UTXO").
 dictionary TxOut {
+  /// The value of the output, in satoshis.
   u64 value;
+
+  /// The script which must be satisfied for the output to be spent.
   Script script_pubkey;
 };
 
+/// Represents the observed position of some chain data.
 [Enum]
 interface ChainPosition {
+  /// The chain data is seen as confirmed, and in anchored by `A`.
   Confirmed(ConfirmationBlockTime confirmation_block_time);
+
+  /// The chain data is not confirmed and last seen in the mempool at this timestamp.
   Unconfirmed(u64 timestamp);
 };
 
@@ -376,6 +418,7 @@ dictionary CanonicalTx {
   ChainPosition chain_position;
 };
 
+/// Builds a [`FullScanRequest`].
 interface FullScanRequestBuilder {
   [Throws=RequestBuilderError]
   FullScanRequestBuilder inspect_spks_for_all_keychains(FullScanScriptInspector inspector);
@@ -384,6 +427,7 @@ interface FullScanRequestBuilder {
   FullScanRequest build();
 };
 
+/// Builds a [`SyncRequest`].
 interface SyncRequestBuilder {
   [Throws=RequestBuilderError]
   SyncRequestBuilder inspect_spks(SyncScriptInspector inspector);
@@ -406,6 +450,7 @@ interface FullScanScriptInspector {
   void inspect(KeychainKind keychain, u32 index, Script script);
 };
 
+/// A changeset for [`Wallet`].
 interface ChangeSet {};
 
 // ------------------------------------------------------------------------