docs: add dartdoc comments to core public API classes

[j-kon]

The generated lib/bdk.dart file exposes the full BDK API surface to Dart consumers but currently has no dartdoc comments on any of its public classes or methods. This means:

• dart doc produces empty or near-empty documentation pages
• pub.dev shows no API docs, which affects package scoring
• Developers have no in-editor guidance on usage, disposal, thread safety, or error handling

At a minimum, the following classes should have documented:

• Wallet — lifecycle, persistence, and disposal expectations
• Descriptor — construction patterns and supported script types
• Mnemonic — entropy, wordcount, and language options
• ElectrumClient / EsploraClient — connection setup and async behaviour
• Transaction / Psbt — building, signing, and broadcasting flow
• Exception types — there are 360+ exception classes; at least the common ones should explain when they're thrown

Since lib/bdk.dart is generated by UniFFI, the docs may need to be injected via UDL annotations or a post-generation script rather than edited directly.

[as1ndu]

Hi,

I happy to help with the docs.

[j-kon]

Thanks for offering to help, @as1ndu!

One constraint worth knowing upfront: lib/bdk.dart is generated by uniffi-dart from the bdk-ffi Rust crate, so edits to that file get overwritten on the next bindings regeneration. Two viable approaches:

Option A — Contribute upstream to bdk-ffi
If uniffi-dart threads Rust doc comments (///) through to the generated output, the right place to add them is in the bdk-ffi source itself. This would benefit the Swift, Kotlin, and Python bindings automatically. Worth checking the uniffi-dart templates to see if doc comment passthrough is already supported.

Option B — Post-generation injection script
Write a script (Dart or Python) that patches lib/bdk.dart after generation, inserting /// dartdoc comments before each class/method. The script would live in this repo and run as part of the bindings update workflow.

Option A is preferable if uniffi-dart supports it since it stays in sync automatically. Option B gives full control but requires manual upkeep each time bindings are regenerated.

A good starting point regardless of approach: the Wallet class — it is the entry point for most consumers and has the most nuanced lifecycle (construction vs Wallet.load, persistence, disposal semantics).

Happy to review whatever direction you take!