Fill in top-level docs for onion message offline peer interception.

lightning/src/events/mod.rs

@@ -1036,14 +1036,25 @@ pub enum Event {
 	///
 	/// [`ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx`]: crate::util::config::ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx
 	BumpTransaction(BumpTransactionEvent),
+	/// We received an onion message that is intended to be forwarded to a peer
+	/// that is currently offline. This event will only be generated if the
+	/// `OnionMessenger` was initialized with
+	/// [`OnionMessenger::new_with_offline_peer_interception`], see its docs.
 	///
+	/// [`OnionMessenger::new_with_offline_peer_interception`]: crate::onion_message::messenger::OnionMessenger::new_with_offline_peer_interception
 	OnionMessageForOfflinePeer {
 		/// The node id of the offline peer.
 		peer_node_id: PublicKey,
 		/// The onion message intended to be forwarded to `peer_node_id`.
 		message: msgs::OnionMessage,
 	},
+	/// Indicates that an onion message supporting peer has come online and it may
+	/// be time to forward any onion messages that were previously intercepted for
+	/// them. This event will only be generated if the `OnionMessenger` was
+	/// initialized with
+	/// [`OnionMessenger::new_with_offline_peer_interception`], see its docs.
 	///
+	/// [`OnionMessenger::new_with_offline_peer_interception`]: crate::onion_message::messenger::OnionMessenger::new_with_offline_peer_interception
 	OnionMessagePeerConnected {
 		/// The node id of the peer we just connected to, who advertises support for
 		/// onion messages.

lightning/src/onion_message/messenger.rs

@@ -722,7 +722,27 @@ where
 		)
 	}
 
+	/// Similar to [`Self::new`], but rather than dropping onion messages that are
+	/// intended to be forwarded to offline peers, we will intercept them for
+	/// later forwarding.
 	///
+	/// Interception flow:
+	/// 1. If an onion message for an offline peer is received, `OnionMessenger` will
+	///    generate an [`Event::OnionMessageForOfflinePeer`]. Event handlers can
+	///    then choose to persist this onion message for later forwarding, or drop
+	///    it.
+	/// 2. When the offline peer later comes back online, `OnionMessenger` will
+	///    generate an [`Event::OnionMessagePeerConnected`]. Event handlers will
+	///    then fetch all previously intercepted onion messages for this peer.
+	/// 3. Once the stored onion messages are fetched, they can finally be
+	///    forwarded to the now-online peer via [`Self::forward_onion_message`].
+	///
+	/// # Note
+	///
+	/// LDK will not rate limit how many [`Event::OnionMessageForOfflinePeer`]s
+	/// are generated, so it is the caller's responsibility to limit how many
+	/// onion messages are persisted and only persist onion messages for relevant
+	/// peers.
 	pub fn new_with_offline_peer_interception(
 		entropy_source: ES, node_signer: NS, logger: L, message_router: MR, offers_handler: OMH,
 		custom_handler: CMH