Update docs and add pending changelog

lightning/src/util/events.rs

@@ -350,8 +350,8 @@ pub enum Event {
 		/// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel
 		user_channel_id: u128,
 	},
-	/// Indicates we've received (an offer of) money! Just gotta dig out that payment preimage and
-	/// feed it to [`ChannelManager::claim_funds`] to get it....
+	/// Indicates that a payment is inbound and needs to be claimed via calling
+	/// [`ChannelManager::claim_funds`] with the preimage given in [`PaymentPurpose`].
 	///
 	/// Note that if the preimage is not known, you should call
 	/// [`ChannelManager::fail_htlc_backwards`] to free up resources for this HTLC and avoid
@@ -364,15 +364,18 @@ pub enum Event {
 	/// LDK will not stop an inbound payment from being paid multiple times, so multiple
 	/// `PaymentClaimable` events may be generated for the same payment.
 	///
+	/// # Note
+	/// This event used to be called `PaymentReceived` in LDK versions 0.0.112 and earlier.
+	///
 	/// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
 	/// [`ChannelManager::fail_htlc_backwards`]: crate::ln::channelmanager::ChannelManager::fail_htlc_backwards
 	PaymentClaimable {
-		/// The node that received the payment.
-		/// This is useful to identify payments which were received via [phantom node payments].
+		/// The node that will receive the payment after it has been claimed.
+		/// This is useful to identify payments received via [phantom nodes].
 		/// This field will always be filled in when the event was generated by LDK versions
 		/// 0.0.113 and above.
 		///
-		/// [phantom node payments]: crate::chain::keysinterface::PhantomKeysManager
+		/// [phantom nodes]: crate::chain::keysinterface::PhantomKeysManager
 		receiver_node_id: Option<PublicKey>,
 		/// The hash for which the preimage should be handed to the ChannelManager. Note that LDK will
 		/// not stop you from registering duplicate payment hashes for inbound payments.
@@ -403,18 +406,18 @@ pub enum Event {
 	/// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
 	PaymentClaimed {
 		/// The node that received the payment.
-		/// This is useful to identify payments which were received via [phantom node payments].
+		/// This is useful to identify payments which were received via [phantom nodes].
 		/// This field will always be filled in when the event was generated by LDK versions
 		/// 0.0.113 and above.
 		///
-		/// [phantom node payments]: crate::chain::keysinterface::PhantomKeysManager
+		/// [phantom nodes]: crate::chain::keysinterface::PhantomKeysManager
 		receiver_node_id: Option<PublicKey>,
 		/// The payment hash of the claimed payment. Note that LDK will not stop you from
 		/// registering duplicate payment hashes for inbound payments.
 		payment_hash: PaymentHash,
 		/// The value, in thousandths of a satoshi, that this payment is for.
 		amount_msat: u64,
-		/// The purpose of this claimed payment, i.e. whether the payment was for an invoice or a
+		/// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a
 		/// spontaneous payment.
 		purpose: PaymentPurpose,
 	},

pending_changelog/elias-event-renaming.txt

@@ -0,0 +1,5 @@
+## API Updates
+
+## Backwards Compatibilty
+- The event formerly known as `PaymentReceived` is now called
+  `PaymentClaimable`.