From 62cabfbc6d9a081f010208566ab2f057f63b0cfa Mon Sep 17 00:00:00 2001
From: Rob N <rob.netzke@gmail.com>
Date: Tue, 10 Sep 2024 16:55:07 -1000
Subject: [PATCH] doc: futher library documentation

---
 src/builder.rs |  6 +++---
 src/lib.rs     | 14 ++++++++++----
 2 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/src/builder.rs b/src/builder.rs
index 277069b..c2b09d2 100644
--- a/src/builder.rs
+++ b/src/builder.rs
@@ -61,7 +61,7 @@ const PEEK_INDEX: u32 = 20;
 const RECOMMENDED_PEERS: u8 = 2;
 
 #[derive(Debug)]
-/// Construct a light client from higher level components.
+/// Construct a light client from a [`Wallet`] reference.
 pub struct LightClientBuilder<'a> {
     wallet: &'a Wallet,
     peers: Option<Vec<TrustedPeer>>,
@@ -73,7 +73,7 @@ pub struct LightClientBuilder<'a> {
 }
 
 impl<'a> LightClientBuilder<'a> {
-    /// Construct a new node builder
+    /// Construct a new node builder.
     pub fn new(wallet: &'a Wallet) -> Self {
         Self {
             wallet,
@@ -163,7 +163,7 @@ impl<'a> LightClientBuilder<'a> {
         cp
     }
 
-    /// Build a light client node and a client to interact with the node
+    /// Build a light client node and a client to interact with the node.
     pub fn build(self) -> Result<(Node, Client<KeychainKind>), Error> {
         let network = self.wallet.network();
         let mut node_builder = NodeBuilder::new(network);
diff --git a/src/lib.rs b/src/lib.rs
index 2610a71..11d663b 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -136,7 +136,7 @@ use bdk_chain::{
     IndexedTxGraph,
 };
 use bdk_chain::{ConfirmationBlockTime, TxUpdate};
-use kyoto::{IndexedBlock, TxBroadcast};
+use kyoto::{IndexedBlock, SyncUpdate, TxBroadcast};
 
 use crate::logger::NodeMessageHandler;
 
@@ -147,7 +147,7 @@ pub mod logger;
 pub use bdk_chain::local_chain::MissingGenesisError;
 pub use kyoto::{
     ClientError, DatabaseError, HeaderCheckpoint, Node, NodeBuilder, NodeMessage, NodeState,
-    Receiver, ScriptBuf, SyncUpdate, Transaction, TrustedPeer, TxBroadcastPolicy, Txid, Warning,
+    Receiver, ScriptBuf, Transaction, TrustedPeer, TxBroadcastPolicy, Txid, Warning,
     MAINNET_HEADER_CP, SIGNET_HEADER_CP,
 };
 
@@ -168,7 +168,7 @@ impl<K> Client<K>
 where
     K: fmt::Debug + Clone + Ord,
 {
-    /// Build a light client from a [`KeychainTxOutIndex`] and checkpoint
+    /// Build a light client from a [`KeychainTxOutIndex`] and [`CheckPoint`].
     pub fn from_index(
         cp: CheckPoint,
         index: &KeychainTxOutIndex<K>,
@@ -185,6 +185,11 @@ where
 
     /// Return the most recent update from the node once it has synced to the network's tip.
     /// This may take a significant portion of time during wallet recoveries or dormant wallets.
+    /// Note that you may call this method in a loop as long as the [`Node`] is running.
+    ///
+    /// A reference to a [`NodeMessageHandler`] is required, which handles events emitted from a running
+    /// [`Node`]. Production applications should define how the application handles these events and displays
+    /// them to end users.
     pub async fn update(&mut self, logger: &dyn NodeMessageHandler) -> Option<FullScanResult<K>> {
         let mut chain_changeset = BTreeMap::new();
         while let Ok(message) = self.receiver.recv().await {
@@ -274,7 +279,8 @@ where
             .map_err(Error::from)
     }
 
-    /// Add more scripts to the node. Could this just check a SPK index?
+    /// Add more scripts to the node. For example, a user may reveal a Bitcoin address to receive a payment,
+    /// so this script should be added to the [`Node`].
     pub async fn add_script(&self, script: impl Into<ScriptBuf>) -> Result<(), Error> {
         self.sender.add_script(script).await.map_err(Error::from)
     }