Documentation improvements

Author: jurvis

lightning/src/ln/channelmanager.rs

@@ -1701,9 +1701,11 @@ where
 	/// Returns in an undefined order recent payments that -- if not fulfilled -- have yet to find a
 	/// successful path, or have unresolved HTLCs.
 	///
-	/// This can be useful for figuring out whether or not a payment needs to be retried.
-	/// In general, if it is not listed here, you should consider retrying it if not
-	/// [`RecentPaymentDetails::Fulfilled`].
+	/// This can be useful for payments that may have been prepared, but ultimately not sent, as a
+	/// result of a crash. If such a payment exists, is not listed here, and an
+	/// [`Event::PaymentSent`] event has yet to be received, you may consider retrying the payment.
+	///
+	/// [`Event::PaymentSent`]: events::Event::PaymentSent
 	pub fn list_recent_payments(&self) -> Vec<RecentPaymentDetails> {
 		self.pending_outbound_payments.pending_outbound_payments.lock().unwrap().iter()
 			.filter_map(|(_, pending_outbound_payment)| match pending_outbound_payment {
@@ -2482,6 +2484,11 @@ where
 	/// irrevocably committed to on our end. In such a case, do NOT retry the payment with a
 	/// different route unless you intend to pay twice!
 	///
+	/// Additionally,  if the process of sending a payment begins, but we crash before send_payment
+	/// returns (or prior to MonitorUpdate completion if you're using
+	/// [`ChannelMonitorUpdateStatus::InProgress`]), the payment may be lost on restart. See
+	/// [`ChannelManager::list_recent_payments`] for more information.
+	///
 	/// payment_secret is unrelated to payment_hash (or PaymentPreimage) and exists to authenticate
 	/// the sender to the recipient and prevent payment-probing (deanonymization) attacks. For
 	/// newer nodes, it will be provided to you in the invoice. If you do not have one, the Route
@@ -2494,6 +2501,7 @@ where
 	///
 	/// [`Event::PaymentSent`]: events::Event::PaymentSent
 	/// [`PeerManager::process_events`]: crate::ln::peer_handler::PeerManager::process_events
+	/// [`ChannelMonitorUpdateStatus::InProgress`]: crate::chain::ChannelMonitorUpdateStatus::InProgress
 	pub fn send_payment(&self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>, payment_id: PaymentId) -> Result<(), PaymentSendFailure> {
 		let best_block_height = self.best_block.read().unwrap().height();
 		self.pending_outbound_payments