Remove examples folder, add rustdoc examples

.github/workflows/cont_integration.yml

@@ -54,6 +54,8 @@ jobs:
           cargo update -p idna_adapter --precise "1.1.0"
           cargo update -p base64ct --precise "1.6.0"
           cargo update -p minreq --precise "2.13.2"
+          cargo update -p rayon-core --precise "1.12.1"
+          cargo update -p rayon --precise "1.10.0"
       - name: Pin dependencies for MSRV
         if: matrix.rust.version == '1.63.0'
         run: ./ci/pin-msrv.sh
@@ -166,30 +168,3 @@ jobs:
           name: Clippy Results
           args: --all-features --all-targets -- -D warnings
 
-  build-examples:
-    needs: prepare
-    name: Build & Test Examples
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        example-dir:
-          - example_cli
-          - example_bitcoind_rpc_polling
-          - example_electrum
-          - example_esplora
-    steps:
-      - name: checkout
-        uses: actions/checkout@v4
-        with:
-          persist-credentials: false
-      - name: Install Rust toolchain
-        uses: actions-rs/toolchain@v1
-        with:
-          toolchain: ${{ needs.prepare.outputs.rust_version }}
-          override: true
-          profile: minimal
-      - name: Rust Cache
-        uses: Swatinem/[email protected]
-      - name: Build
-        working-directory: examples/${{ matrix.example-dir }}
-        run: cargo build

Cargo.toml

@@ -8,10 +8,6 @@ members = [
     "crates/esplora",
     "crates/bitcoind_rpc",
     "crates/testenv",
-    "examples/example_cli",
-    "examples/example_electrum",
-    "examples/example_esplora",
-    "examples/example_bitcoind_rpc_polling",
 ]
 
 [workspace.package]

crates/chain/src/indexed_tx_graph.rs

@@ -87,6 +87,15 @@ where
     ///
     /// The underlying `TxGraph` is initialized with `TxGraph::default()`, and the provided
     /// `index`er is used as‐is (since there are no existing transactions to process).
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use bdk_chain::{keychain_txout::KeychainTxOutIndex, BlockId, IndexedTxGraph};
+    ///
+    /// let index = KeychainTxOutIndex::<&str>::new(10, true);
+    /// let graph = IndexedTxGraph::<BlockId, _>::new(index);
+    /// ```
     pub fn new(index: I) -> Self {
         Self {
             index,
@@ -367,6 +376,18 @@ where
     /// Relevancy is determined by the internal [`Indexer::is_tx_relevant`] implementation of `I`.
     /// A transaction that conflicts with a relevant transaction is also considered relevant.
     /// Irrelevant transactions in `block` will be ignored.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use bdk_chain::{IndexedTxGraph, keychain_txout::KeychainTxOutIndex, BlockId};
+    /// use bitcoin::Block;
+    ///
+    /// let mut graph = IndexedTxGraph::<BlockId, _>::new(KeychainTxOutIndex::<&str>::new(10, true));
+    /// # let block = Block { header: bitcoin::block::Header::from(bitcoin::constants::genesis_block(bitcoin::Network::Bitcoin).header), txdata: vec![] };
+    ///
+    /// let changeset = graph.apply_block_relevant(&block, 100);
+    /// ```
     pub fn apply_block_relevant(
         &mut self,
         block: &Block,

crates/chain/src/indexer/keychain_txout.rs

@@ -453,6 +453,22 @@ impl<K: Clone + Ord + Debug> KeychainTxOutIndex<K> {
     /// (one keychain just becomes the defacto owner of that spk arbitrarily) but this may have
     /// subtle implications up the application stack like one UTXO being missing from one keychain
     /// because it has been assigned to another which produces the same script pubkey.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use bdk_chain::keychain_txout::KeychainTxOutIndex;
+    /// use bdk_chain::miniscript::{Descriptor, DescriptorPublicKey};
+    /// # use std::str::FromStr;
+    ///
+    /// let mut index = KeychainTxOutIndex::<&str>::new(10, true);
+    /// let desc = Descriptor::<DescriptorPublicKey>::from_str(
+    ///     "wpkh([d34db33f/84h/0h/0h]xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0/*)"
+    /// )?;
+    ///
+    /// index.insert_descriptor("external", desc)?;
+    /// # Ok::<_, Box<dyn std::error::Error>>(())
+    /// ```
     pub fn insert_descriptor(
         &mut self,
         keychain: K,
@@ -834,6 +850,22 @@ impl<K: Clone + Ord + Debug> KeychainTxOutIndex<K> {
     ///  1. The descriptor has no wildcard and already has one script revealed.
     ///  2. The descriptor has already revealed scripts up to the numeric bound.
     ///  3. There is no descriptor associated with the given keychain.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use bdk_chain::keychain_txout::KeychainTxOutIndex;
+    /// use bdk_chain::miniscript::{Descriptor, DescriptorPublicKey};
+    /// # use std::str::FromStr;
+    ///
+    /// let mut index = KeychainTxOutIndex::<&str>::new(10, true);
+    /// let desc = Descriptor::<DescriptorPublicKey>::from_str(
+    ///     "wpkh([d34db33f/84h/0h/0h]xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0/*)"
+    /// ).unwrap();
+    /// index.insert_descriptor("external", desc).unwrap();
+    /// let (spk, changeset) = index.reveal_next_spk("external").unwrap();
+    /// assert_eq!(spk.0, 0);
+    /// ```
     pub fn reveal_next_spk(&mut self, keychain: K) -> Option<(Indexed<ScriptBuf>, ChangeSet)> {
         let mut changeset = ChangeSet::default();
         let indexed_spk = self._reveal_next_spk(&mut changeset, keychain)?;

crates/chain/src/tx_graph.rs

@@ -655,6 +655,24 @@ impl<A: Anchor> TxGraph<A> {
     /// * A smaller witness has precedence over a larger witness.
     /// * If the witness sizes are the same, we prioritize the two witnesses with lexicographical
     ///   order.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use bdk_chain::{tx_graph::TxGraph, BlockId};
+    /// use bitcoin::Transaction;
+    ///
+    /// let mut graph = TxGraph::<BlockId>::default();
+    /// let tx = Transaction {
+    ///     version: bitcoin::transaction::Version::ONE,
+    ///     lock_time: bitcoin::locktime::absolute::LockTime::ZERO,
+    ///     input: vec![],
+    ///     output: vec![],
+    /// };
+    ///
+    /// let changeset = graph.insert_tx(tx.clone());
+    /// assert_eq!(changeset.txs.len(), 1);
+    /// ```
     pub fn insert_tx<T: Into<Arc<Transaction>>>(&mut self, tx: T) -> ChangeSet<A> {
         // This returns `Some` only if the merged tx is different to the `original_tx`.
         fn _merge_tx_witnesses(
@@ -1247,6 +1265,37 @@ impl<A: Anchor> TxGraph<A> {
     ///
     /// This is the infallible version of [`try_filter_chain_unspents`].
     ///
+    /// # Example
+    ///
+    /// ```
+    /// use bdk_chain::local_chain::LocalChain;
+    /// use bdk_chain::{tx_graph::TxGraph, BlockId, CanonicalizationParams};
+    /// use bitcoin::{Amount, OutPoint, TxOut};
+    /// use std::sync::Arc;
+    ///
+    /// let mut graph = TxGraph::<BlockId>::default();
+    /// let chain = LocalChain::from_blocks(
+    ///     [(
+    ///         0,
+    ///         bitcoin::constants::genesis_block(bitcoin::Network::Bitcoin).block_hash(),
+    ///     )]
+    ///     .into_iter()
+    ///     .collect(),
+    /// )
+    /// .unwrap();
+    ///
+    /// // Get unspent outputs
+    /// let outpoints = vec![(0, OutPoint::default())];
+    /// let utxos: Vec<_> = graph
+    ///     .filter_chain_unspents(
+    ///         &chain,
+    ///         chain.tip().block_id(),
+    ///         CanonicalizationParams::default(),
+    ///         outpoints,
+    ///     )
+    ///     .collect();
+    /// ```
+    ///
     /// [`try_filter_chain_unspents`]: Self::try_filter_chain_unspents
     pub fn filter_chain_unspents<'a, C: ChainOracle<Error = Infallible> + 'a, OI: Clone + 'a>(
         &'a self,
@@ -1315,6 +1364,34 @@ impl<A: Anchor> TxGraph<A> {
     ///
     /// This is the infallible version of [`try_balance`].
     ///
+    /// # Example
+    ///
+    /// ```
+    /// use bdk_chain::local_chain::LocalChain;
+    /// use bdk_chain::{tx_graph::TxGraph, Balance, BlockId, CanonicalizationParams};
+    /// use bitcoin::OutPoint;
+    ///
+    /// let graph = TxGraph::<BlockId>::default();
+    /// let chain = LocalChain::from_blocks(
+    ///     [(
+    ///         0,
+    ///         bitcoin::constants::genesis_block(bitcoin::Network::Bitcoin).block_hash(),
+    ///     )]
+    ///     .into_iter()
+    ///     .collect(),
+    /// )
+    /// .unwrap();
+    ///
+    /// let outpoints = vec![(0, OutPoint::default())];
+    /// let balance = graph.balance(
+    ///     &chain,
+    ///     chain.tip().block_id(),
+    ///     CanonicalizationParams::default(),
+    ///     outpoints,
+    ///     |_, _| true,
+    /// );
+    /// ```
+    ///
     /// [`try_balance`]: Self::try_balance
     pub fn balance<C: ChainOracle<Error = Infallible>, OI: Clone>(
         &self,

crates/electrum/src/bdk_electrum_client.rs

@@ -28,6 +28,16 @@ pub struct BdkElectrumClient<E> {
 
 impl<E: ElectrumApi> BdkElectrumClient<E> {
     /// Creates a new bdk client from a [`electrum_client::ElectrumApi`]
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use bdk_electrum::{electrum_client, BdkElectrumClient};
+    ///
+    /// let client = electrum_client::Client::new("ssl://electrum.blockstream.info:50002")?;
+    /// let bdk_client = BdkElectrumClient::new(client);
+    /// # Ok::<_, electrum_client::Error>(())
+    /// ```
     pub fn new(client: E) -> Self {
         Self {
             inner: client,
@@ -90,6 +100,27 @@ impl<E: ElectrumApi> BdkElectrumClient<E> {
     ///   [`CalculateFeeError::MissingTxOut`] error if those `TxOut`s are not present in the
     ///   transaction graph.
     ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use bdk_core::{spk_client::FullScanRequest, BlockId, CheckPoint};
+    /// use bdk_electrum::BdkElectrumClient;
+    /// # use bdk_electrum::electrum_client;
+    /// # use electrum_client::bitcoin::{constants, Network};
+    ///
+    /// # let client = electrum_client::Client::new("ssl://electrum.blockstream.info:50002")?;
+    /// # let bdk_client = BdkElectrumClient::new(client);
+    /// let request = FullScanRequest::<&str>::builder()
+    ///     .chain_tip(CheckPoint::new(BlockId {
+    ///         height: 0,
+    ///         hash: constants::genesis_block(Network::Bitcoin).block_hash(),
+    ///     }))
+    ///     .build();
+    ///
+    /// let response = bdk_client.full_scan(request, 10, 50, false)?;
+    /// # Ok::<_, electrum_client::Error>(())
+    /// ```
+    ///
     /// [`bdk_chain`]: ../bdk_chain/index.html
     /// [`CalculateFeeError::MissingTxOut`]: ../bdk_chain/tx_graph/enum.CalculateFeeError.html#variant.MissingTxOut
     /// [`Wallet.calculate_fee`]: ../bdk_wallet/struct.Wallet.html#method.calculate_fee
@@ -173,6 +204,24 @@ impl<E: ElectrumApi> BdkElectrumClient<E> {
     /// If the scripts to sync are unknown, such as when restoring or importing a keychain that
     /// may include scripts that have been used, use [`full_scan`] with the keychain.
     ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use bdk_core::bitcoin::ScriptBuf;
+    /// use bdk_core::spk_client::SyncRequest;
+    /// use bdk_electrum::BdkElectrumClient;
+    /// # use bdk_electrum::electrum_client;
+    ///
+    /// # let client = electrum_client::Client::new("ssl://electrum.blockstream.info:50002")?;
+    /// # let bdk_client = BdkElectrumClient::new(client);
+    /// let request = SyncRequest::builder()
+    ///     .spks([ScriptBuf::new_op_return(&[0x00; 20])])
+    ///     .build();
+    ///
+    /// let response = bdk_client.sync(request, 50, false)?;
+    /// # Ok::<_, electrum_client::Error>(())
+    /// ```
+    ///
     /// [`full_scan`]: Self::full_scan
     /// [`bdk_chain`]: ../bdk_chain/index.html
     /// [`CalculateFeeError::MissingTxOut`]: ../bdk_chain/tx_graph/enum.CalculateFeeError.html#variant.MissingTxOut

crates/esplora/src/blocking_ext.rs

@@ -26,6 +26,27 @@ pub trait EsploraExt {
     /// `stop_gap` script pubkeys with no associated transactions. `parallel_requests` specifies
     /// the maximum number of HTTP requests to make in parallel.
     ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use bdk_core::bitcoin::{constants, Network};
+    /// use bdk_core::spk_client::FullScanRequest;
+    /// use bdk_core::{BlockId, CheckPoint};
+    /// use bdk_esplora::{esplora_client, EsploraExt};
+    ///
+    /// let client = esplora_client::Builder::new("https://blockstream.info/api").build_blocking();
+    ///
+    /// let request = FullScanRequest::<&str>::builder()
+    ///     .chain_tip(CheckPoint::new(BlockId {
+    ///         height: 0,
+    ///         hash: constants::genesis_block(Network::Bitcoin).block_hash(),
+    ///     }))
+    ///     .build();
+    ///
+    /// let response = client.full_scan(request, 10, 5)?;
+    /// # Ok::<_, Box<dyn std::error::Error>>(())
+    /// ```
+    ///
     /// Refer to [crate-level docs](crate) for more.
     fn full_scan<K: Ord + Clone, R: Into<FullScanRequest<K>>>(
         &self,