f - Touch up chainmonitor docs based on review feedback

Author: jkczyz

lightning/src/chain/chainmonitor.rs

@@ -9,9 +9,13 @@
 
 //! Logic to connect off-chain channel management with on-chain transaction monitoring.
 //!
-//! [`ChainMonitor`] is a simple implementation of [`chain::Watch`] used both to process blocks and
-//! to update on-chain [`ChannelMonitor`]s accordingly. If any on-chain events need further
-//! processing, it will make those available as [`MonitorEvent`]s to be consumed.
+//! [`ChainMonitor`] is an implementation of [`chain::Watch`] used both to process blocks and to
+//! update [`ChannelMonitor`]s accordingly. If any on-chain events need further processing, it will
+//! make those available as [`MonitorEvent`]s to be consumed.
+//!
+//! `ChainMonitor` is parameterized by an optional chain source, which must implement the
+//! [`chain::Filter`] trait. This provides a mechanism to signal new relevant outputs back to light
+//! clients, such that transactions spending those outputs are included in block data.
 //!
 //! `ChainMonitor` may be used directly to monitor channels locally or as a part of a distributed
 //! setup to monitor channels remotely. In the latter case, a custom `chain::Watch` implementation
@@ -20,6 +24,7 @@
 //! servicing `ChannelMonitor` updates from the client.
 //!
 //! [`ChainMonitor`]: struct.ChainMonitor.html
+//! [`chain::Filter`]: ../trait.Filter.html
 //! [`chain::Watch`]: ../trait.Watch.html
 //! [`ChannelMonitor`]: ../channelmonitor/struct.ChannelMonitor.html
 //! [`MonitorEvent`]: ../channelmonitor/enum.MonitorEvent.html
@@ -44,10 +49,12 @@ use std::ops::Deref;
 ///
 /// Connected and disconnected blocks must be provided to `ChainMonitor` as documented by
 /// [`chain::Watch`]. May be used in conjunction with [`ChannelManager`] to monitor channels locally
-/// or used independently to monitor channels remotely.
+/// or used independently to monitor channels remotely. See the [module-level documentation] for
+/// details.
 ///
 /// [`chain::Watch`]: ../trait.Watch.html
 /// [`ChannelManager`]: ../../ln/channelmanager/struct.ChannelManager.html
+/// [module-level documentation]: index.html
 pub struct ChainMonitor<ChanSigner: ChannelKeys, C: Deref, T: Deref, F: Deref, L: Deref>
 	where C::Target: chain::Filter,
         T::Target: BroadcasterInterface,
@@ -75,7 +82,7 @@ impl<ChanSigner: ChannelKeys, C: Deref, T: Deref, F: Deref, L: Deref> ChainMonit
 	///
 	/// Calls back to [`chain::Filter`] if any monitor indicated new outputs to watch, returning
 	/// `true` if so. In this case, if providing pre-filtered blocks, the caller should re-fetch the
-	/// block to obtain updated `txdata` and recall `block_connected`.
+	/// block to obtain updated `txdata` and re-call `block_connected`.
 	///
 	/// [`ChannelMonitor::block_connected`]: ../channelmonitor/struct.ChannelMonitor.html#method.block_connected
 	/// [`chain::Watch::release_pending_monitor_events`]: ../trait.Watch.html#tymethod.release_pending_monitor_events
@@ -131,7 +138,7 @@ impl<ChanSigner: ChannelKeys, C: Deref, T: Deref, F: Deref, L: Deref> ChainMonit
 		}
 	}
 
-	/// Adds or updates the monitor which monitors the channel referred to by the given outpoint.
+	/// Adds the monitor that watches the channel referred to by the given outpoint.
 	///
 	/// Calls back to [`chain::Filter`] with the funding transaction and outputs to watch.
 	///
@@ -159,7 +166,7 @@ impl<ChanSigner: ChannelKeys, C: Deref, T: Deref, F: Deref, L: Deref> ChainMonit
 		Ok(())
 	}
 
-	/// Updates the monitor which monitors the channel referred to by the given outpoint.
+	/// Updates the monitor that watches the channel referred to by the given outpoint.
 	fn update_monitor(&self, outpoint: OutPoint, update: ChannelMonitorUpdate) -> Result<(), MonitorUpdateError> {
 		let mut monitors = self.monitors.lock().unwrap();
 		match monitors.get_mut(&outpoint) {