Try focus the example crates on having useful snippets

[stevenroose]

Currently many of the example crates are working CLIs. I doubt however that anyone will ever actually run these CLIs.

The downside of them being CLIs is that they are over 50% just boilerplate for the CLIs.

What I think most developers are looking for are copyable snippets on how to do things themselves.

Imagine a new user that never used BDK and he wants a wallet with bitcoind, try figure out what pieces of code you have to copy from https://github.com/bitcoindevkit/bdk/blob/master/example-crates/example_bitcoind_rpc_polling/src/main.rs and which you don't need? It's not easy :sweat_smile:

[LLFourn]

I'm a little confused by the "over 50% boilerplate" comment because I don't really see much boilerplate there. You'd have to copy paste most of that main function somewhere in your app to use block-by-block RPC.

I do agree that CLI interactions to not produce the most copy pastable code if you are making a server or app based wallet etc. But during the stages of development we've been through we've used them successfully to validate designs and APIs. Every single fully working example we've added has led to major API revisions/additions. I think a good part of that is forcing the implementer to make it fully working end-to-end and to use it. Another advantage is that they could be tested if we put the effort in because they all have the same commands but just fetch blockchain data differently.

We could put the fully-working CLI examples in their own section since they may indeed have a different audience that more "snippet" kind of examples. I'm not sure how many useful snippet kind of examples we can produce though that (i) actually work, (ii) are copy pastable, (iii) are not a cli and (iv) we can easily tell when they break by running them.

[danielabrozzoni]

I agree that our examples are too difficult to understand.

We could put the fully-working CLI examples in their own section since they may indeed have a different audience that more "snippet" kind of examples.

This should be the end goal imho, and it is what we had in bdk 0.29 with the examples directory + bdk-cli. It was easier to have examples focused on explaining one thing, clear of boilerplate, with important snippets were highlighted - something that we don't have in the current structure, where some important functions are shared between examples and, as such, a bit "hidden" in example_cli.

That being said, I agree that the current examples have served us as developers, and I don't have in mind how we could refactor things right now.

For now, I think we should focus on making the examples we have way more user friendly. I'm thinking:

• Moving the cli boilerplate in separate files, or at least at the end of the file
• Decent comments everywhere (example_esplora is in a good state imho)
• Maybe splitting the code into separate functions could be helpful. Taking esplora as an example, our code looks like this:

  let indexed_tx_graph_changeset = match &esplora_cmd {
      EsploraCommands::Scan {
          stop_gap,
          scan_options,
          ..
      } => {
          // things
      }
      EsploraCommands::Sync {
          mut unused_spks,
          all_spks,
          mut utxos,
          mut unconfirmed,
          scan_options,
          ..
      } => {
          // other things
      }

but it could look like:

// docs
fn scan(....) -> .... {

}

// docs
fn sync(....) -> .... {

}

and then

let indexed_tx_graph_changeset = match &esplora_cmd {
        EsploraCommands::Scan {
            stop_gap,
            scan_options,
            ..
        } => {
            scan(...)
        }
        EsploraCommands::Sync {
            mut unused_spks,
            all_spks,
            mut utxos,
            mut unconfirmed,
            scan_options,
            ..
        } => {
            sync(...)
        }

I feel like this could help with highlighting the important parts of the code, so that the user is met with a few functions it can copy-paste.

[LLFourn]

@danielabrozzoni it's looks great but when you fill in the .... I have a feeling it won't any longer because of all the arguments you need to pass. Potentially, you could have structs like Scan and Sync and impl them with the same method like run(db: Mutex<...>, tx_graph: ..., chain: ...). This allows the reader to see the distinction between the cli args and the application state stuff like db, chain etc.