Flesh out docs on PendingHTLCRouting

Now that `PendingHTLCRouting` is public, its docs should be
meaningful to developers not working directly on LDK, and thus
needs substantially more information than it previously had.

This adds much of that information.

Author: TheBlueMatt

lightning/src/ln/channelmanager.rs

@@ -109,50 +109,79 @@ use crate::ln::script::ShutdownScript;
 // Alternatively, we can fill an outbound HTLC with a HTLCSource::OutboundRoute indicating this is
 // our payment, which we can use to decode errors or inform the user that the payment was sent.
 
-/// Routing info for an inbound HTLC onion.
+/// Information about where a received HTLC('s onion) has indicated the HTLC should go.
 #[derive(Clone)] // See Channel::revoke_and_ack for why, tl;dr: Rust bug
 pub enum PendingHTLCRouting {
-	/// A forwarded HTLC.
+	/// An HTLC which should be forwarded on to another node.
 	Forward {
-		/// BOLT 4 onion packet.
+		/// The onion which should be included in the forwarded HTLC, telling the next hop what to
+		/// do with the HTLC.
 		onion_packet: msgs::OnionPacket,
-		/// The SCID from the onion that we should forward to. This could be a real SCID or a fake one
-		/// generated using `get_fake_scid` from the scid_utils::fake_scid module.
+		/// The short channel ID of the channel which we were instructed to forward this HTLC to.
+		///
+		/// This could be a real on-chain SCID, an SCID alias, or some other SCID which has meaning
+		/// to the receiving node, such as one returned from
+		/// [`ChannelManager::get_intercept_scid`] or [`ChannelManager::get_phantom_scid`].
 		short_channel_id: u64, // This should be NonZero<u64> eventually when we bump MSRV
 		/// Set if this HTLC is being forwarded within a blinded path.
 		blinded: Option<BlindedForward>,
 	},
-	/// An HTLC paid to an invoice (supposedly) generated by us.
-	/// At this point, we have not checked that the invoice being paid was actually generated by us,
-	/// but rather it's claiming to pay an invoice of ours.
+	/// The onion indicates that this is a payment for an invoice (supposedly) generated by us.
+	///
+	/// Note that at this point, we have not checked that the invoice being paid was actually
+	/// generated by us, but rather it's claiming to pay an invoice of ours.
 	Receive {
-		/// Payment secret and total msat received.
+		/// Information about the amount the sender intended to pay and (potential) proof that this
+		/// is a payment for an invoice we generated. This proof of payment is is also used for
+		/// linking MPP parts of a larger payment.
 		payment_data: msgs::FinalOnionHopData,
-		/// See [`RecipientOnionFields::payment_metadata`] for more info.
+		/// Additional data which we (allegedly) instructed the sender to include in the onion.
+		///
+		/// For HTLCs received by LDK, this will ultimately be exposed in
+		/// [`Event::PaymentClaimable::onion_fields`] as
+		/// [`RecipientOnionFields::payment_metadata`].
 		payment_metadata: Option<Vec<u8>>,
 		/// CLTV expiry of the received HTLC.
+		///
 		/// Used to track when we should expire pending HTLCs that go unclaimed.
 		incoming_cltv_expiry: u32,
-		/// Shared secret derived using a phantom node secret key. If this field is Some, the
-		/// payment was sent to a phantom node (one hop beyond the current node), but can be
-		/// settled by this node.
+		/// If the onion had forwarding instructions to one of our phantom node SCIDs, this will
+		/// provide the onion shared secret used to decrypt the next level of forwarding
+		/// instructions.
 		phantom_shared_secret: Option<[u8; 32]>,
-		/// See [`RecipientOnionFields::custom_tlvs`] for more info.
+		/// Custom TLVs which were set by the sender.
+		///
+		/// For HTLCs received by LDK, this will ultimately be exposed in
+		/// [`Event::PaymentClaimable::onion_fields`] as
+		/// [`RecipientOnionFields::custom_tlvs`].
 		custom_tlvs: Vec<(u64, Vec<u8>)>,
 	},
-	/// Incoming keysend (sender provided the preimage in a TLV).
+	/// The onion indicates that this is for payment to us but which contains the preimage for
+	/// claiming included, and is unrelated to any invoice we'd previously generated (aka a
+	/// "keysend" or "spontaneous" payment).
 	ReceiveKeysend {
-		/// This was added in 0.0.116 and will break deserialization on downgrades.
+		/// Information about the amount the sender intended to pay and possibly a token to
+		/// associate MPP parts of a larger payment.
+		///
+		/// This will only be filled in if receiving MPP keysend payments is enabled, and it being
+		/// present will cause deserialization to fail on versions of LDK prior to 0.0.116.
 		payment_data: Option<msgs::FinalOnionHopData>,
 		/// Preimage for this onion payment. This preimage is provided by the sender and will be
 		/// used to settle the spontaneous payment.
 		payment_preimage: PaymentPreimage,
-		/// See [`RecipientOnionFields::payment_metadata`] for more info.
+		/// Additional data which we (allegedly) instructed the sender to include in the onion.
+		///
+		/// For HTLCs received by LDK, this will ultimately bubble back up as
+		/// [`RecipientOnionFields::payment_metadata`].
 		payment_metadata: Option<Vec<u8>>,
 		/// CLTV expiry of the received HTLC.
+		///
 		/// Used to track when we should expire pending HTLCs that go unclaimed.
 		incoming_cltv_expiry: u32,
-		/// See [`RecipientOnionFields::custom_tlvs`] for more info.
+		/// Custom TLVs which were set by the sender.
+		///
+		/// For HTLCs received by LDK, these will ultimately bubble back up as
+		/// [`RecipientOnionFields::custom_tlvs`].
 		custom_tlvs: Vec<(u64, Vec<u8>)>,
 	},
 }