Remove examples folder, add rustdoc examples

Author: kwsantiago

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

@@ -77,6 +77,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::{IndexedTxGraph, keychain_txout::KeychainTxOutIndex};
+    ///
+    /// let index = KeychainTxOutIndex::<&str>::new(10);
+    /// let graph = IndexedTxGraph::new(index);
+    /// ```
     pub fn new(index: I) -> Self {
         Self {
             index,
@@ -351,6 +360,18 @@ where
     ///
     /// Relevancy is determined by the internal [`Indexer::is_tx_relevant`] implementation of `I`.
     /// Irrelevant transactions in `txs` 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));
+    /// # 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);
+    /// 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,16 @@ 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;
+    ///
+    /// let mut index = KeychainTxOutIndex::<&str>::new(10);
+    /// let (idx, spk, changeset) = index.reveal_next_spk("external").unwrap();
+    /// assert_eq!(idx.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;
+    /// use bitcoin::Transaction;
+    ///
+    /// let mut graph = TxGraph::<()>::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,24 @@ impl<A: Anchor> TxGraph<A> {
     ///
     /// This is the infallible version of [`try_filter_chain_unspents`].
     ///
+    /// # Example
+    ///
+    /// ```
+    /// use bdk_chain::{tx_graph::TxGraph, BlockId, CanonicalizationParams};
+    /// use bdk_chain::local_chain::LocalChain;
+    /// use bitcoin::{OutPoint, TxOut, Amount};
+    /// use std::sync::Arc;
+    ///
+    /// let mut graph = TxGraph::<BlockId>::default();
+    /// let chain = LocalChain::from_blocks([
+    ///     (0, BlockId { height: 0, hash: bitcoin::constants::genesis_block(bitcoin::Network::Bitcoin).block_hash() })
+    /// ].into_iter().collect());
+    ///
+    /// // Get unspent outputs
+    /// let outpoints = vec![(0, OutPoint::default())];
+    /// let utxos: Vec<_> = graph.filter_chain_unspents(&chain, chain.tip(), 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 +1351,22 @@ impl<A: Anchor> TxGraph<A> {
     ///
     /// This is the infallible version of [`try_balance`].
     ///
+    /// # Example
+    ///
+    /// ```
+    /// use bdk_chain::{tx_graph::TxGraph, Balance, BlockId, CanonicalizationParams};
+    /// use bdk_chain::local_chain::LocalChain;
+    /// use bitcoin::OutPoint;
+    ///
+    /// let graph = TxGraph::<BlockId>::default();
+    /// let chain = LocalChain::from_blocks([
+    ///     (0, BlockId { height: 0, hash: bitcoin::constants::genesis_block(bitcoin::Network::Bitcoin).block_hash() })
+    /// ].into_iter().collect());
+    /// 
+    /// let outpoints = vec![(0, OutPoint::default())];
+    /// let balance = graph.balance(&chain, chain.tip(), 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::{BdkElectrumClient, electrum_client};
+    ///
+    /// 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,23 @@ impl<E: ElectrumApi> BdkElectrumClient<E> {
     ///   [`CalculateFeeError::MissingTxOut`] error if those `TxOut`s are not present in the
     ///   transaction graph.
     ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use bdk_electrum::BdkElectrumClient;
+    /// use bdk_core::spk_client::FullScanRequest;
+    /// # use bdk_electrum::electrum_client;
+    ///
+    /// # let client = electrum_client::Client::new("ssl://electrum.blockstream.info:50002")?;
+    /// # let bdk_client = BdkElectrumClient::new(client);
+    /// let request = FullScanRequest::<&str>::builder()
+    ///     .chain_tip(Default::default())
+    ///     .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 +200,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_electrum::BdkElectrumClient;
+    /// use bdk_core::spk_client::SyncRequest;
+    /// use bdk_core::bitcoin::ScriptBuf;
+    /// # 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,24 @@ 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_esplora::{EsploraExt, esplora_client};
+    /// use bdk_core::spk_client::FullScanRequest;
+    /// use bdk_core::bitcoin::Network;
+    ///
+    /// let client = esplora_client::Builder::new("https://blockstream.info/api")
+    ///     .build_blocking();
+    ///
+    /// let request = FullScanRequest::<&str>::builder()
+    ///     .chain_tip(Default::default())
+    ///     .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,