improve docs

Author: jurvis

lightning/src/ln/channelmanager.rs

@@ -1204,7 +1204,9 @@ impl ChannelDetails {
 	}
 }
 
-/// Used to express the status of payments that are currently pending resolution.
+/// Used to express the status of payments that are currently pending resolution. They do not
+/// include only payments that are currently inflight, but also those who may have yet to find a
+/// path or have outstanding HTLCs.
 #[derive(Debug, PartialEq)]
 pub enum RecentPaymentDetails {
 	/// When a payment is still being sent and awaiting successful delivery.
@@ -1217,16 +1219,16 @@ pub enum RecentPaymentDetails {
 		total_msat: u64,
 	},
 	/// When a pending payment is fulfilled, we continue tracking it until all pending HTLCs have
-	/// been resolved. These payments will only cease being tracked upon receiving or handling
-	/// [`Event::PaymentSent`].
+	/// been resolved. Upon receiving [`Event::PaymentSent`], we delay for a couple of seconds
+	/// before the payment is removed from tracking.
 	Fulfilled {
 		/// Hash of the payment that was claimed.
 		payment_hash: Option<PaymentHash>,
 	},
-	/// After a payment is explicitly abandoned by calling [`ChannelManager::abandon_payment`], they
-	/// are marked as abandoned until an [`Event::PaymentFailed`] event is generated. A payment
-	/// could also be marked as abandoned if pathfinding fails repeatedly and we will no longer
-	/// retry sending.
+	/// After a payment is explicitly abandoned by calling [`ChannelManager::abandon_payment`], it
+	/// is marked as abandoned until an [`Event::PaymentFailed`] event is generated. A payment
+	/// could also be marked as abandoned if pathfinding fails repeatedly or retries have been
+	/// exhausted.
 	Abandoned {
 		/// Hash of the payment that we have given up trying to send.
 		payment_hash: PaymentHash,
@@ -1800,7 +1802,7 @@ impl<M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelManager<M, T, K, F
 		self.list_channels_with_filter(|&(_, ref channel)| channel.is_live())
 	}
 
-	/// Gets a list of payments in ramdom order that are currently pending resolution.
+	/// Gets a list of payments in random order that are currently pending resolution.
 	pub fn list_pending_payments(&self) -> Vec<RecentPaymentDetails> {
 		self.pending_outbound_payments.lock().unwrap().iter()
 			.filter_map(|(_, pending_outbound_payment)| match pending_outbound_payment {