f - rewrite docs

Author: jkczyz

lightning/src/events/mod.rs

@@ -722,17 +722,14 @@ pub enum Event {
 	///
 	/// This event will only be generated if [`UserConfig::manually_handle_bolt12_invoices`] is set.
 	/// Use [`ChannelManager::send_payment_for_bolt12_invoice`] to pay the invoice or
-	/// [`ChannelManager::abandon_payment`] to abandon the associated payment. Must be paid before
-	/// [`Bolt12Invoice::relative_expiry`] has elapsed since [`Bolt12Invoice::created_at`].
-	/// Attempting to pay the invoice after this time will result in an [`Event::PaymentFailed`].
+	/// [`ChannelManager::abandon_payment`] to abandon the associated payment. See those docs for
+	/// further details.
 	///
 	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 	/// [`Refund`]: crate::offers::refund::Refund
 	/// [`UserConfig::manually_handle_bolt12_invoices`]: crate::util::config::UserConfig::manually_handle_bolt12_invoices
 	/// [`ChannelManager::send_payment_for_bolt12_invoice`]: crate::ln::channelmanager::ChannelManager::send_payment_for_bolt12_invoice
 	/// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
-	/// [`Bolt12Invoice::relative_expiry`]: crate::offers::invoice::Bolt12Invoice::relative_expiry
-	/// [`Bolt12Invoice::created_at`]: crate::offers::invoice::Bolt12Invoice::created_at
 	InvoiceReceived {
 		/// The `payment_id` associated with payment for the invoice.
 		payment_id: PaymentId,

lightning/src/ln/channelmanager.rs

@@ -4001,7 +4001,10 @@ where
 	/// The invoice's `payer_metadata` is used to authenticate that the invoice was indeed requested
 	/// before attempting a payment. [`Bolt12PaymentError::UnexpectedInvoice`] is returned if this
 	/// fails or if the encoded `payment_id` is not recognized. The latter may happen once the
-	/// invoice is paid and the payment no longer tracked.
+	/// payment is no longer tracked because the payment was attempted after:
+	/// - an invoice for the `payment_id` was already paid,
+	/// - one timer tick has elapsed since initially requesting the invoice when paying an offer, or
+	/// - the refund corresponding to the invoice has already expired.
 	///
 	/// Attempting to pay the same invoice twice while the first payment is still pending will
 	/// result in a [`Bolt12PaymentError::DuplicateInvoice`].