From 5dd4ce74cf762184c318e17d5c1d094e47179d69 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BF=97=E5=AE=87?= <hello@evanlinjin.me>
Date: Fri, 10 Mar 2023 13:40:27 +1300
Subject: [PATCH] More documentation improvements

---
 crates/esplora/README.md     | 35 ++++++++++++++++++++++++++++++++++-
 crates/esplora/src/lib.rs    |  6 +-----
 crates/file_store/Cargo.toml |  4 ++++
 crates/file_store/README.md  | 10 ++++++++++
 crates/file_store/src/lib.rs |  1 +
 5 files changed, 50 insertions(+), 6 deletions(-)
 create mode 100644 crates/file_store/README.md

diff --git a/crates/esplora/README.md b/crates/esplora/README.md
index 637a7d52a..9880115b1 100644
--- a/crates/esplora/README.md
+++ b/crates/esplora/README.md
@@ -1,3 +1,36 @@
 # BDK Esplora
 
-BDK Esplora client library for updating the `bdk_chain` structures.
+BDK Esplora extends [`esplora_client`](crate::esplora_client) to update [`bdk_chain`] structures
+from an Esplora server.
+
+## Usage
+
+There are two versions of the extension trait (blocking and async).
+
+For blocking-only:
+```toml
+bdk_esplora = { version = "0.1", features = ["blocking"] }
+```
+
+For async-only:
+```toml
+bdk_esplora = { version = "0.1", features = ["async"] }
+```
+
+For async-only (with https):
+```toml
+bdk_esplora = { version = "0.1", features = ["async-https"] }
+```
+
+To use the extension trait:
+
+```rust,no_run
+// for blocking
+use bdk_esplora::EsploraExt;
+// for async
+use bdk_esplora::EsploraAsyncExt;
+```
+
+<!-- BDK Esplora client library for updating the `bdk_chain` structures. -->
+
+<!-- [`esplora_client`]: https://docs.rs/esplora-client/latest -->
diff --git a/crates/esplora/src/lib.rs b/crates/esplora/src/lib.rs
index 5964dc5b3..8398fcb35 100644
--- a/crates/esplora/src/lib.rs
+++ b/crates/esplora/src/lib.rs
@@ -1,8 +1,4 @@
-//! This crate is used for updating structures of [`bdk_chain`] with data from an esplora server.
-//!
-//! The star of the show is the  [`EsploraExt::scan`] method which scans for relevant
-//! blockchain data (via esplora) and outputs a [`KeychainScan`](bdk_chain::keychain::KeychainScan).
-
+#![doc = include_str!("../README.md")]
 use bdk_chain::ConfirmationTime;
 use esplora_client::TxStatus;
 
diff --git a/crates/file_store/Cargo.toml b/crates/file_store/Cargo.toml
index 09ed12130..55b04d4f9 100644
--- a/crates/file_store/Cargo.toml
+++ b/crates/file_store/Cargo.toml
@@ -4,6 +4,10 @@ version = "0.0.1"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/bitcoindevkit/bdk"
+documentation = "https://docs.rs/bdk_file_store"
+keywords = ["bitcoin", "persist", "persistence", "bdk", "file", "store"]
+authors = ["Bitcoin Dev Kit Developers"]
+readme = "README.md"
 
 [dependencies]
 bdk_chain = { path = "../chain", version = "0.3.1", features = [ "serde", "miniscript" ] }
diff --git a/crates/file_store/README.md b/crates/file_store/README.md
new file mode 100644
index 000000000..076142f89
--- /dev/null
+++ b/crates/file_store/README.md
@@ -0,0 +1,10 @@
+# BDK File Store
+
+This is a simple append-only flat file implementation of
+[`Persist`](`bdk_chain::keychain::persist::Persist`).
+
+The main structure is [`KeychainStore`](`crate::KeychainStore`), which can be used with [`bdk`]'s
+`Wallet` to persist wallet data into a flat file.
+
+[`bdk`]: https://docs.rs/bdk/latest
+[`bdk_chain`]: https://docs.rs/bdk_chain/latest
diff --git a/crates/file_store/src/lib.rs b/crates/file_store/src/lib.rs
index 85dc52298..e33474194 100644
--- a/crates/file_store/src/lib.rs
+++ b/crates/file_store/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 mod file_store;
 use bdk_chain::{
     keychain::{KeychainChangeSet, KeychainTracker, PersistBackend},