f Improve docs and usage example

Author: tnull

lightning-transaction-sync/src/esplora.rs

@@ -18,8 +18,9 @@ use core::ops::Deref;
 
 /// Synchronizes LDK with a given [`Esplora`] server.
 ///
-/// Needs to be registerd with a [`ChainMonitor`] via the [`Filter`] interface to be informed of
-/// transactions and outputs to montor.
+/// Needs to be registered with a [`ChainMonitor`] via the [`Filter`] interface to be informed of
+/// transactions and outputs to monitor for on-chain confirmation, unconfirmation, and
+/// reconfirmation.
 ///
 /// [`Esplora`]: https://github.com/Blockstream/electrs
 /// [`ChainMonitor`]: lightning::chain::chainmonitor::ChainMonitor
@@ -49,7 +50,7 @@ where
 		EsploraSyncClient::from_client(client, logger)
 	}
 
-	/// Returns a new [`EsploraSyncClient`] object using the given esplora client.
+	/// Returns a new [`EsploraSyncClient`] object using the given Esplora client.
 	pub fn from_client(client: EsploraClientType, logger: L) -> Self {
 		let sync_state = MutexType::new(SyncState::new());
 		let queue = std::sync::Mutex::new(FilterQueue::new());
@@ -61,10 +62,17 @@ where
 		}
 	}
 
-	/// Synchronizes the given confirmables via the [`Confirm`] interface. This method should be
-	/// called regularly to keep LDK up-to-date with current chain data.
+	/// Synchronizes the given `confirmables` via their [`Confirm`] interface implementations. This
+	/// method should be called regularly to keep LDK up-to-date with current chain data.
+	///
+	/// For example, instances of [`ChannelManager`] and [`ChainMonitor`] can be informed about the
+	/// newest on-chain activity related to the items previously registered via the [`Filter`]
+	/// interface.
 	///
 	/// [`Confirm`]: lightning::chain::Confirm
+	/// [`ChainMonitor`]: lightning::chain::chainmonitor::ChainMonitor
+	/// [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager
+	/// [`Filter`]: lightning::chain::Filter
 	#[maybe_async]
 	pub fn sync(&self, confirmables: Vec<&(dyn Confirm + Sync + Send)>) -> Result<(), TxSyncError> {
 		// This lock makes sure we're syncing once at a time.

lightning-transaction-sync/src/lib.rs

@@ -1,6 +1,56 @@
 //! Provides utilities for syncing LDK via the transaction-based [`Confirm`] interface.
 //!
+//! The provided synchronization clients need to be registered with a [`ChainMonitor`] via the
+//! [`Filter`] interface. Then, the respective `fn sync` needs to be called with the [`Confirm`]
+//! implementations to be synchronized, i.e., usually instances of [`ChannelManager`] and
+//! [`ChainMonitor`].
+//!
+//! ## Features and Backend Support
+//!
+//!- `esplora_blocking` enables syncing against an Esplora backend based on a blocking.
+//!- `esplora_async` enables syncing against an Esplora backend based on an async client.
+//!
+//! ## Usage Example:
+//!
+//! ```ignore
+//! let tx_sync = Arc::new(EsploraSyncClient::new(
+//! 	esplora_server_url,
+//! 	Arc::clone(&some_logger),
+//! ));
+//!
+//! let chain_monitor = Arc::new(ChainMonitor::new(
+//! 	Some(Arc::clone(&tx_sync)),
+//! 	Arc::clone(&some_broadcaster),
+//! 	Arc::clone(&some_logger),
+//! 	Arc::clone(&some_fee_estimator),
+//! 	Arc::clone(&some_persister),
+//! ));
+//!
+//! let channel_manager = Arc::new(ChannelManager::new(
+//! 	Arc::clone(&some_fee_estimator),
+//! 	Arc::clone(&chain_monitor),
+//! 	Arc::clone(&some_broadcaster),
+//! 	Arc::clone(&some_router),
+//! 	Arc::clone(&some_logger),
+//! 	Arc::clone(&some_entropy_source),
+//! 	Arc::clone(&some_node_signer),
+//! 	Arc::clone(&some_signer_provider),
+//! 	user_config,
+//! 	chain_params,
+//! ));
+//!
+//! let confirmables = vec![
+//! 	&*channel_manager as &(dyn Confirm + Sync + Send),
+//! 	&*chain_monitor as &(dyn Confirm + Sync + Send),
+//! ];
+//!
+//! tx_sync.sync(confirmables).unwrap();
+//! ```
+//!
 //! [`Confirm`]: lightning::chain::Confirm
+//! [`Filter`]: lightning::chain::Filter
+//! [`ChainMonitor`]: lightning::chain::chainmonitor::ChainMonitor
+//! [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager
 
 // Prefix these with `rustdoc::` when we update our MSRV to be >= 1.52 to remove warnings.
 #![deny(broken_intra_doc_links)]