f - Rewrite WatchedOutput docs to be less vague

Author: jkczyz

lightning/src/chain/mod.rs

@@ -132,7 +132,7 @@ pub trait Filter: Send + Sync {
 	/// Registers interest in spends of a transaction output.
 	///
 	/// Optionally, when `output.block_hash` is set, should return any transaction spending the
-	/// output that is found in the corresponding block at the given index.
+	/// output that is found in the corresponding block along with its index.
 	///
 	/// This return value is useful for Electrum clients in order to supply in-block descendant
 	/// transactions which otherwise were not included. This is not necessary for other clients if
@@ -143,13 +143,17 @@ pub trait Filter: Send + Sync {
 
 /// A transaction output watched by a [`ChannelMonitor`] for spends on-chain.
 ///
-/// Used to convey to a [`Filter`] an output identified by `outpoint` having `script_pubkey` as the
-/// spending condition. If `block_hash` is `Some`, this indicates the output may have been spent in
-/// the corresponding block.
+/// Used to convey to a [`Filter`] such an output with a given spending condition. Any transaction
+/// spending the output must be given to [`ChannelMonitor::block_connected`] either directly or via
+/// the return value of [`Filter::register_output`].
 ///
-/// [`ChannelMonitor`]: channelmonitor/struct.ChannelMonitor.html
+/// If `block_hash` is `Some`, this indicates the output was created in the corresponding block and
+/// may have been spent there. See [`Filter::register_output`] for details.
+///
+/// [`ChannelMonitor`]: channelmonitor::ChannelMonitor
+/// [`ChannelMonitor::block_connected`]: channelmonitor::ChannelMonitor::block_connected
 pub struct WatchedOutput {
-	/// Block where the transaction output may have been spent.
+	/// First block where the transaction output may have been spent.
 	pub block_hash: Option<BlockHash>,
 
 	/// Outpoint identifying the transaction output.