From f734ca203d179a668e84b48e15d86a52e8e4b2fb 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 | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/bdk-ffi/src/bdk.udl b/bdk-ffi/src/bdk.udl
index 1c716777..7bbdff12 100644
--- a/bdk-ffi/src/bdk.udl
+++ b/bdk-ffi/src/bdk.udl
@@ -268,24 +268,36 @@ 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;
 
   Amount trusted_spendable;
@@ -293,21 +305,39 @@ dictionary Balance {
   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);
 };
 
@@ -326,6 +356,7 @@ dictionary CanonicalTx {
   ChainPosition chain_position;
 };
 
+/// Builds a [`FullScanRequest`].
 interface FullScanRequestBuilder {
   [Throws=RequestBuilderError]
   FullScanRequestBuilder inspect_spks_for_all_keychains(FullScanScriptInspector inspector);
@@ -334,6 +365,7 @@ interface FullScanRequestBuilder {
   FullScanRequest build();
 };
 
+/// Builds a [`SyncRequest`].
 interface SyncRequestBuilder {
   [Throws=RequestBuilderError]
   SyncRequestBuilder inspect_spks(SyncScriptInspector inspector);
@@ -356,6 +388,7 @@ interface FullScanScriptInspector {
   void inspect(KeychainKind keychain, u32 index, Script script);
 };
 
+/// A changeset for [`Wallet`].
 interface ChangeSet {};
 
 // ------------------------------------------------------------------------