Move samples into tests

.gitignore

@@ -15,5 +15,5 @@ xcuserdata
 .lsp
 .clj-kondo
 .idea
-android/src/main/kotlin/org/bitcoindevkit/bdk.kt
+bdk-android/lib/src/main/kotlin/org/bitcoindevkit/bdk.kt
-jvm/src/main/kotlin/org/bitcoindevkit/bdk.kt
+bdk-jvm/lib/src/main/kotlin/org/bitcoindevkit/bdk.kt

api-docs/build.gradle.kts

@@ -29,7 +29,7 @@ tasks.withType<org.jetbrains.dokka.gradle.DokkaTask>().configureEach {
             moduleName.set("bdk-android")
             moduleVersion.set("0.9.0")
             includes.from("Module.md")
-            samples.from("src/main/kotlin/org/bitcoindevkit/Samples.kt")
+            samples.from("src/test/kotlin/org/bitcoindevkit/Samples.kt")
         }
     }
 }

api-docs/src/main/kotlin/org/bitcoindevkit/Samples.kt

@@ -1,13 +0,0 @@
-package org.bitcoindevkit
-
-class Samples {
-    val blockchainConfig: BlockchainConfig = BlockchainConfig.Electrum(
-        ElectrumConfig(
-            url = "ssl://electrum.blockstream.info:60002",
-            socks5 = null,
-            retry = 5u,
-            timeout = null,
-            stopGap = 10u
-        )
-    )
-}

api-docs/src/main/kotlin/org/bitcoindevkit/bdk.kt

@@ -37,14 +37,40 @@ enum class AddressIndex {
     /** Return a new address after incrementing the current descriptor index. */
     NEW,
 
-    /**
+    /** Return the address for the current descriptor index if it has not been used in a received transaction. Otherwise return a new address as with `AddressIndex.NEW`. Use with caution, if the wallet has not yet detected an address has been used it could return an already used address. This function is primarily meant for situations where the caller is untrusted; for example when deriving donation addresses on-demand for a public web page. */
-     * Return the address for the current descriptor index if it has not been used in a received transaction. Otherwise return a new address as with `AddressIndex.NEW`. Use with caution, if the wallet has not yet detected an address has been used it could return an already used address. This function is primarily meant for situations where the caller is untrusted; for example when deriving donation addresses on-demand for a public web page.
-     */
     LAST_UNUSED,
 }
 
+/**
+ * Balance differentiated in various categories
+ *
+ * @sample org.bitcoindevkit.balanceSample
+ */
+data class Balance (
+    /** All coinbase outputs not yet matured. */
+    var immature: ULong,
+
+    /** Unconfirmed UTXOs generated by a wallet tx. */
+    var trustedPending: ULong,
+
+    /** Unconfirmed UTXOs received from an external wallet. */
+    var untrustedPending: ULong,
+
+    /** Confirmed and immediately spendable balance. */
+    var confirmed: ULong,
+
+    /** The sum of trustedPending and confirmed coins. */
+    var spendable: ULong,
+
+    /** The whole balance visible to the wallet. */
+    var total: ULong
+)
+
 /**
  * Type that can contain any of the database configurations defined by the library.
+ *
+ * @sample org.bitcoindevkit.memoryDatabaseConfigExample
+ * @sample org.bitcoindevkit.sqliteDatabaseConfigExample
  */
 sealed class DatabaseConfig {
     /** Configuration for an in-memory database */
@@ -79,7 +105,7 @@ data class SledDbConfiguration(
 /**
  * Configuration for an Electrum blockchain.
  *
- * @sample org.bitcoindevkit.Samples.blockchainConfig
+ * @sample org.bitcoindevkit.electrumBlockchainConfigExample
  */
 data class ElectrumConfig (
     /** URL of the Electrum server (such as ElectrumX, Esplora, BWT) may start with `ssl://` or `tcp://` and include a port, e.g. `ssl://electrum.blockstream.info:60002`. */

api-docs/src/test/kotlin/org/bitcoindevkit/Samples.kt

@@ -0,0 +1,44 @@
+package org.bitcoindevkit
+
+fun balanceSample() {
+    object LogProgress : Progress {
+        override fun update(progress: Float, message: String?) {}
+    }
+
+    val memoryDatabaseConfig = DatabaseConfig.Memory
+    private val blockchainConfig = BlockchainConfig.Electrum(
+        ElectrumConfig(
+            "ssl://electrum.blockstream.info:60002",
+            null,
+            5u,
+            null,
+            200u
+        )
+    )
+    val wallet = Wallet(descriptor, null, Network.TESTNET, memoryDatabaseConfig)
+    val blockchain = Blockchain(blockchainConfig)
+    wallet.sync(blockchain, LogProgress)
+
+    val balance: Balance = wallet.getBalance()
+    println("Total wallet balance is ${balance.total}")
+}
+
+fun electrumBlockchainConfigExample() {
+    val blockchainConfig = BlockchainConfig.Electrum(
+        ElectrumConfig(
+            "ssl://electrum.blockstream.info:60002",
+            null,
+            5u,
+            null,
+            200u
+        )
+    )
+}
+
+fun memoryDatabaseConfigExample() {
+    val memoryDatabaseConfig = DatabaseConfig.Memory
+}
+
+fun sqliteDatabaseConfigExample() {
+    val databaseConfig = DatabaseConfig.Sqlite(SqliteDbConfiguration("bdk-sqlite"))
+}