f - Rewrite EventsProvider docs

Author: jkczyz

lightning/src/chain/chainmonitor.rs

@@ -308,6 +308,9 @@ where C::Target: chain::Filter,
 	}
 }
 
+/// Provides [`SpendableOutputs`] events produced from each [`ChannelMonitor`] upon maturity.
+///
+/// [`SpendableOutputs`]: events::Event::SpendableOutputs
 impl<ChannelSigner: Sign, C: Deref, T: Deref, F: Deref, L: Deref, P: Deref> events::EventsProvider for ChainMonitor<ChannelSigner, C, T, F, L, P>
 	where C::Target: chain::Filter,
 	      T::Target: BroadcasterInterface,

lightning/src/ln/channelmanager.rs

@@ -3572,6 +3572,14 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> MessageSend
 	}
 }
 
+/// Provides events that must be periodically handled.
+///
+/// An [`EventHandler`] may safely call back to the provider in order to handle an event. However,
+/// it must not call [`Writeable::write`] as doing so would result in a deadlock.
+///
+/// Pending events are persisted as part of [`ChannelManager`]. While these events are cleared when
+/// processed, an [`EventHandler`] must be able to handle previously seen events when restarting
+/// from an old state.
 impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> EventsProvider for ChannelManager<Signer, M, T, K, F, L>
 where
 	M::Target: chain::Watch<Signer>,

lightning/src/util/events.rs

@@ -383,10 +383,25 @@ pub trait MessageSendEventsProvider {
 
 /// A trait indicating an object may generate events.
 ///
-/// Events are processed by a handler given to [`process_pending_events`]. Therefore, implementors
-/// should be mindful to avoid lock reentrancy if a handler may call back into the provider.
+/// Events are processed by passing an [`EventHandler`] to [`process_pending_events`].
+///
+/// # Implementations
+///
+/// See [`process_pending_events`] for expectations around event processing.
+///
+/// When implementing this trait, be mindful that handlers may call back into the provider and thus
+/// deadlocking must be avoided. Therefore, be sure to document expectations around how the handler
+/// may safely use the provider.
+///
+/// # Uses
+///
+/// When using this trait, [`process_pending_events`] will call the [`handle_event`] for each
+/// pending event since the last invocation. The handler must either act upon the event immediately
+/// or preserve it for later handling. Be sure to consult the provider's trait documentation on the
+/// implication of processing events and how a handler itself may safely use the provider.
 ///
 /// [`process_pending_events`]: Self::process_pending_events
+/// [`handle_event`]: EventHandler::handle_event
 pub trait EventsProvider {
 	/// Processes any events generated since the last call using the given event handler.
 	///
@@ -400,8 +415,7 @@ pub trait EventsProvider {
 pub trait EventHandler {
 	/// Handles the given [`Event`].
 	///
-	/// See [`EventsProvider::process_pending_events`] for details that must be considered when
-	/// implementing this method.
+	/// See [`EventsProvider`] for details that must be considered when implementing this method.
 	fn handle_event(&self, event: Event);
 }