Provide more color in filter registration methods

A few years ago we had repeated user confusion dealing with the
`Filter` methods and exactly how they differ. Here we try to add a
bit more color in several ways as suggested by users in a few
places - listing examples of why the methods are used as well as
ensuring its clearly communicated that not all parameters need be
used.

Fixes #1069

diff --git a/lightning/src/chain/mod.rs b/lightning/src/chain/mod.rs
index a8afc7a1acbda8310ad7fb2d6744bca9974465f9..93c8aa197382ae6ab9221528557e07b0ffe71808 100644 (file)
--- a/lightning/src/chain/mod.rs
+++ b/lightning/src/chain/mod.rs
@@ -327,6 +327,11 @@ pub trait Watch<ChannelSigner: WriteableEcdsaChannelSigner> {
 pub trait Filter {
        /// Registers interest in a transaction with `txid` and having an output with `script_pubkey` as
        /// a spending condition.
+       ///
+       /// This may be used, for example, to monitor for when a funding transaction confirms.
+       ///
+       /// The `script_pubkey` is provided for informational purposes and may be useful for block
+       /// sources which only support filtering on scripts.
        fn register_tx(&self, txid: &Txid, script_pubkey: &Script);
 
        /// Registers interest in spends of a transaction output.
@@ -335,6 +340,9 @@ pub trait Filter {
        /// to ensure that also dependent output spents within an already connected block are correctly
        /// handled, e.g., by re-scanning the block in question whenever new outputs have been
        /// registered mid-processing.
+       ///
+       /// This may be used, for example, to monitor for when a funding output is spent (by any
+       /// transaction).
        fn register_output(&self, output: WatchedOutput);
 }
 
@@ -347,6 +355,9 @@ pub trait Filter {
 /// 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.
 ///
+/// Depending on your block source, you may need one or both of either [`Self::outpoint`] or
+/// [`Self::script_pubkey`].
+///
 /// [`ChannelMonitor`]: channelmonitor::ChannelMonitor
 /// [`ChannelMonitor::block_connected`]: channelmonitor::ChannelMonitor::block_connected
 #[derive(Clone, PartialEq, Eq, Hash)]