Improve docs

Author: jurvis

lightning/src/ln/channelmanager.rs

@@ -1163,8 +1163,8 @@ pub enum RecentPaymentDetails {
 		/// Hash of the payment that is currently being sent but has yet to be fulfilled or
 		/// abandoned.
 		payment_hash: PaymentHash,
-		/// Total amount (in msat) across all paths for this payment, not just the amount currently
-		/// inflight.
+		/// Total amount (in msat, excluding fees) across all paths for this payment,
+		/// not just the amount currently inflight.
 		total_msat: u64,
 	},
 	/// When a pending payment is fulfilled, we continue tracking it until all pending HTLCs have
@@ -2476,6 +2476,8 @@ where
 	/// Value parameters are provided via the last hop in route, see documentation for RouteHop
 	/// fields for more info.
 	///
+	///	# Avoiding Duplicate Payments
+	///
 	/// If a pending payment is currently in-flight with the same [`PaymentId`] provided, this
 	/// method will error with an [`APIError::InvalidRoute`]. Note, however, that once a payment
 	/// is no longer pending (either via [`ChannelManager::abandon_payment`], or handling of an
@@ -2488,12 +2490,19 @@ where
 	/// consider using the [`PaymentHash`] as the key for tracking payments. In that case, the
 	/// [`PaymentId`] should be a copy of the [`PaymentHash`] bytes.
 	///
+	/// Additionally, in the scenario where we begin the process of sending a payment, but crash
+	/// before `send_payment` returns (or prior to [`ChannelMonitorUpdate`] persistence if you're
+	/// using [`ChannelMonitorUpdateStatus::InProgress`]), the payment may be lost on restart. See
+	/// [`ChannelManager::list_recent_payments`] for more information.
+	///
 	/// May generate SendHTLCs message(s) event on success, which should be relayed (e.g. via
 	/// [`PeerManager::process_events`]).
 	///
+	/// # Possible Error States on PaymentSendFailure
+	///
 	/// Each path may have a different return value, and PaymentSendValue may return a Vec with
 	/// each entry matching the corresponding-index entry in the route paths, see
-	/// PaymentSendFailure for more info.
+	/// [`PaymentSendFailure`] for more info.
 	///
 	/// In general, a path may raise:
 	///  * [`APIError::InvalidRoute`] when an invalid route or forwarding parameter (cltv_delta, fee,
@@ -2508,20 +2517,17 @@ 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!
 	///
-	/// Thus, in order to ensure duplicate payments are not sent, if we begin the process of sending
-	/// a payment, but crash before `send_payment` returns (or prior to [`ChannelMonitorUpdate`]
-	/// persistence if you're using [`ChannelMonitorUpdateStatus::InProgress`]), the payment may be
-	/// lost on restart. See [`ChannelManager::list_recent_payments`] for more information.
+	/// # A caution on `payment_secret`
 	///
-	/// 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
-	/// must not contain multiple paths as multi-path payments require a recipient-provided
-	/// payment_secret.
+	/// `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 must not contain multiple paths as multi-path payments require a
+	/// recipient-provided `payment_secret`.
 	///
-	/// If a payment_secret *is* provided, we assume that the invoice had the payment_secret feature
-	/// bit set (either as required or as available). If multiple paths are present in the Route,
-	/// we assume the invoice had the basic_mpp feature set.
+	/// If a `payment_secret` *is* provided, we assume that the invoice had the payment_secret
+	/// feature bit set (either as required or as available). If multiple paths are present in the
+	/// Route, we assume the invoice had the basic_mpp feature set.
 	///
 	/// [`Event::PaymentSent`]: events::Event::PaymentSent
 	/// [`PeerManager::process_events`]: crate::ln::peer_handler::PeerManager::process_events