bdk icon indicating copy to clipboard operation
bdk copied to clipboard

refactor: replace examples with focused rustdoc examples

Open kwsantiago opened this issue 4 months ago • 8 comments

Closes #1973

Changes

  • Removed /examples folder containing CLI-heavy examples
  • Added focused rustdoc examples to key functions:
    • IndexedTxGraph::new() - graph initialization
    • BdkElectrumClient::new() - client creation
    • BdkElectrumClient::sync() - blockchain sync
    • BdkElectrumClient::full_scan() - wallet restoration
    • TxGraph::insert_tx() - transaction insertion
    • TxGraph::balance() - balance calculation
    • TxGraph::filter_chain_unspents() - UTXO retrieval
    • KeychainTxOutIndex::reveal_next_spk() - address generation
    • KeychainTxOutIndex::insert_descriptor() - descriptor setup
    • IndexedTxGraph::apply_block_relevant() - block processing
    • EsploraExt::full_scan() - Esplora wallet scanning
  • Updated Cargo.toml workspace members

Rationale

The previous examples contained 300+ lines of CLI boilerplate that obscured the core BDK functionality. The new rustdoc examples are 10-15 lines each and focus purely on API usage, making them much easier for developers to understand and follow.

The maintained bdk-cli tool serves as the comprehensive CLI example.

kwsantiago avatar Aug 01 '25 13:08 kwsantiago

Thanks for working on this one. It's failing on CI. Make sure to use the 'just' commands and try building the docs locally if that helps with debugging the failures.

oleonardolima avatar Aug 04 '25 18:08 oleonardolima

@oleonardolima thank you. CI "should" be fixed now, at least it is locally. Can we try again?

kwsantiago avatar Aug 05 '25 00:08 kwsantiago

Thanks, there are some unrelated already merged commits, you probably need to do a rebase on top of master. Also, please note that we follow the conventional commits for commit messages, which would also need an update.

oleonardolima avatar Aug 06 '25 18:08 oleonardolima

@oleonardolima ok should be ready to test CI now. Thanks!

kwsantiago avatar Aug 06 '25 18:08 kwsantiago

You'll need to perform another rebase to incorporate the CI updates/fixes, and remove the unrelated merge commit.

oleonardolima avatar Aug 22 '25 18:08 oleonardolima

@oleonardolima should be good now, let me know if there is anything else here.

kwsantiago avatar Aug 22 '25 19:08 kwsantiago

cACK, but haven't done a close review yet. Thanks for hanging in on this one, but looks like it needs another rebase.

notmandatory avatar Sep 25 '25 01:09 notmandatory

I'm sorry for all the rebases you had to do, but you'll need another one to get the latest CI with bumped MSRV.

oleonardolima avatar Oct 18 '25 22:10 oleonardolima