f one comment good, three comments better

Author: TheBlueMatt

lightning/src/ln/channelmanager.rs

@@ -1000,6 +1000,9 @@ enum BackgroundEvent {
 	/// `counterparty_node_id` is not available as the channel has closed from a [`ChannelMonitor`]
 	/// error the other variant is acceptable.
 	///
+	/// Any such events that exist in [`ChannelManager::pending_background_events`] will *also* be
+	/// tracked in [`PeerState::in_flight_monitor_updates`].
+	///
 	/// Note that any such events are lost on shutdown, so in general they must be updates which
 	/// are regenerated on startup.
 	MonitorUpdateRegeneratedOnStartup {
@@ -1290,6 +1293,13 @@ pub(super) struct PeerState<SP: Deref> where SP::Target: SignerProvider {
 	/// Note that the channel may no longer exist. For example if the channel was closed but we
 	/// later needed to claim an HTLC which is pending on-chain, we may generate a monitor update
 	/// for a missing channel.
+	///
+	/// Note that any pending [`BackgroundEvent::MonitorUpdateRegeneratedOnStartup`]s which are
+	/// sitting in [`ChannelManager::pending_background_events`] will *also* be tracked here. This
+	/// avoids a race condition during [`ChannelManager::pending_background_events`] processing
+	/// where we complete one [`ChannelMonitorUpdate`] (but there are more pending) but we conclude
+	/// all pending [`ChannelMonitorUpdate`]s have completed and its safe to run post-completion
+	/// actions.
 	in_flight_monitor_updates: BTreeMap<OutPoint, Vec<ChannelMonitorUpdate>>,
 	/// Map from a specific channel to some action(s) that should be taken when all pending
 	/// [`ChannelMonitorUpdate`]s for the channel complete updating.