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!

[as1ndu]

Hello @j-kon, thanks for the reply.

A few concerns about Option A;

Python doc comments are;

"""
   comment
"""

Kotlin docs are;

/**
 * comment
 */

Dart docs, /// are compatible with Swift docs ///. I feel like this may pollute other projects like Python or Kotlin where the /// syntax is not supported in Python or Kotlin

Option B

May require regex (which can be unpredictable) & even break in case the file's comments are being injected to a modified file out of sync.
I would pick Option B, over A.

However, what do you think of Option C.?
I export required methods, functions or classes to an external file and document them there.
It could be in the file ../main/lib/bdk_dart.dart or a new file

That way;

• We don't mess with the generated dart file in any way (no injections)
• The documentation is permanent
• It's easier to maintain (new methods, classes & functions would simply be exported the standard way)

What do you think of option C?

[j-kon]

Thanks for thinking through Option C, @as1ndu. The separation is attractive, but there is one limitation: lib/bdk_dart.dart already re-exports bdk.dart, and a Dart export does not attach new documentation to the original Wallet, Descriptor, or other generated declarations. We would need to wrap or redeclare the API for those docs to appear, which would create a large second layer to maintain.

On Option A, Rust /// comments are metadata rather than literal syntax copied into every generated language. Each binding generator can render that metadata using Dart, Kotlin, Python, or Swift's own documentation format. I checked bdk-ffi v3.0.0 and it already has useful documentation on Wallet and many of its methods.

The missing link appears to be upstream in uniffi-dart: docstring generation is tracked in Uniffi-Dart/uniffi-dart#59, while modern proc-macro support is tracked in Uniffi-Dart/uniffi-dart#64. Both are still open.

I think investigating that upstream path first gives us the cleanest long-term solution. If it turns out to be too broad, a post-generation step can remain a fallback, but it should include validation so regeneration cannot silently apply docs to the wrong declarations. Would you be interested in looking into the upstream docstring issue first? I would be happy to help review the direction.

[as1ndu]

@j-kon I think Option B would be the best given what you have described. We shall have to discard Option C.

While Option A provides a long term solution, uniffi-dart/issues/59 and /uniffi-dart/issues/64 have been open for close to a year and may take longer.

Option B puts things with in our control and offers a quicker execution.
I am thinking of using a bash script for inserting the documentation. Would that be okay?