Docs improvements

Author: douglaz

fuzz/src/full_stack.rs

@@ -861,7 +861,7 @@ mod tests {
 		// 0085 3d00000000000000000000000000000000000000000000000000000000000000 0900000000000000000000000000000000000000000000000000000000000000 020b00000000000000000000000000000000000000000000000000000000000000 03000000000000000000000000000000 - revoke_and_ack and mac
 		//
 		// 07 - process the now-pending HTLC forward
-		// - client now sends id 1 update_add_htlc and commitment_signed (CHECK 7: SendHTLCs event for node 03020000 with 1 HTLCs for channel 3f000000)
+		// - client now sends id 1 update_add_htlc and commitment_signed (CHECK 7: UpdateHTLCs event for node 03020000 with 1 HTLCs for channel 3f000000)
 		//
 		// - we respond with commitment_signed then revoke_and_ack (a weird, but valid, order)
 		// 030112 - inbound read from peer id 1 of len 18

lightning-invoice/src/utils.rs

@@ -38,7 +38,7 @@ use core::time::Duration;
 ///
 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
 /// in excess of the current time.
-/// 
+///
 /// `duration_since_epoch` is the current time since epoch in seconds.
 ///
 /// You can specify a custom `min_final_cltv_expiry_delta`, or let LDK default it to
@@ -56,7 +56,7 @@ use core::time::Duration;
 /// [`ChannelManager::create_inbound_payment_for_hash`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
 /// [`PhantomRouteHints::channels`]: lightning::ln::channelmanager::PhantomRouteHints::channels
 /// [`MIN_FINAL_CLTV_EXPIRY_DETLA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
-/// 
+///
 /// This can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
 /// available and the current time is supplied by the caller.
 pub fn create_phantom_invoice<ES: Deref, NS: Deref, L: Deref>(
@@ -98,7 +98,7 @@ where
 ///
 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
 /// in excess of the current time.
-/// 
+///
 /// `duration_since_epoch` is the current time since epoch in seconds.
 ///
 /// Note that the provided `keys_manager`'s `NodeSigner` implementation must support phantom
@@ -110,7 +110,7 @@ where
 /// [`ChannelManager::create_inbound_payment`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment
 /// [`ChannelManager::create_inbound_payment_for_hash`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
 /// [`PhantomRouteHints::channels`]: lightning::ln::channelmanager::PhantomRouteHints::channels
-/// 
+///
 /// This can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
 /// available and the current time is supplied by the caller.
 pub fn create_phantom_invoice_with_description_hash<ES: Deref, NS: Deref, L: Deref>(

lightning/src/ln/chan_utils.rs

@@ -8,7 +8,7 @@
 // licenses.
 
 //! Various utilities for building scripts and deriving keys related to channels. These are
-//! largely of interest for those implementing chain::keysinterface::Sign message signing by hand.
+//! largely of interest for those implementing the traits on [`chain::keysinterface`] by hand.
 
 use bitcoin::blockdata::script::{Script,Builder};
 use bitcoin::blockdata::opcodes;

lightning/src/ln/channel.rs

@@ -245,52 +245,52 @@ enum HTLCUpdateAwaitingACK {
 }
 
 /// There are a few "states" and then a number of flags which can be applied:
-/// We first move through init with OurInitSent -> TheirInitSent -> FundingCreated -> FundingSent.
-/// TheirChannelReady and OurChannelReady then get set on FundingSent, and when both are set we
-/// move on to ChannelReady.
-/// Note that PeerDisconnected can be set on both ChannelReady and FundingSent.
-/// ChannelReady can then get all remaining flags set on it, until we finish shutdown, then we
-/// move on to ShutdownComplete, at which point most calls into this channel are disallowed.
+/// We first move through init with `OurInitSent` -> `TheirInitSent` -> `FundingCreated` -> `FundingSent`.
+/// `TheirChannelReady` and `OurChannelReady` then get set on `FundingSent`, and when both are set we
+/// move on to `ChannelReady`.
+/// Note that `PeerDisconnected` can be set on both `ChannelReady` and `FundingSent`.
+/// `ChannelReady` can then get all remaining flags set on it, until we finish shutdown, then we
+/// move on to `ShutdownComplete`, at which point most calls into this channel are disallowed.
 enum ChannelState {
 	/// Implies we have (or are prepared to) send our open_channel/accept_channel message
 	OurInitSent = 1 << 0,
-	/// Implies we have received their open_channel/accept_channel message
+	/// Implies we have received their `open_channel`/`accept_channel` message
 	TheirInitSent = 1 << 1,
-	/// We have sent funding_created and are awaiting a funding_signed to advance to FundingSent.
-	/// Note that this is nonsense for an inbound channel as we immediately generate funding_signed
-	/// upon receipt of funding_created, so simply skip this state.
+	/// We have sent `funding_created` and are awaiting a `funding_signed` to advance to `FundingSent`.
+	/// Note that this is nonsense for an inbound channel as we immediately generate `funding_signed`
+	/// upon receipt of `funding_created`, so simply skip this state.
 	FundingCreated = 4,
-	/// Set when we have received/sent funding_created and funding_signed and are thus now waiting
-	/// on the funding transaction to confirm. The ChannelReady flags are set to indicate when we
+	/// Set when we have received/sent `funding_created` and `funding_signed` and are thus now waiting
+	/// on the funding transaction to confirm. The `ChannelReady` flags are set to indicate when we
 	/// and our counterparty consider the funding transaction confirmed.
 	FundingSent = 8,
-	/// Flag which can be set on FundingSent to indicate they sent us a channel_ready message.
-	/// Once both TheirChannelReady and OurChannelReady are set, state moves on to ChannelReady.
+	/// Flag which can be set on `FundingSent` to indicate they sent us a `channel_ready` message.
+	/// Once both `TheirChannelReady` and `OurChannelReady` are set, state moves on to `ChannelReady`.
 	TheirChannelReady = 1 << 4,
-	/// Flag which can be set on FundingSent to indicate we sent them a channel_ready message.
-	/// Once both TheirChannelReady and OurChannelReady are set, state moves on to ChannelReady.
+	/// Flag which can be set on `FundingSent` to indicate we sent them a `channel_ready` message.
+	/// Once both `TheirChannelReady` and `OurChannelReady` are set, state moves on to `ChannelReady`.
 	OurChannelReady = 1 << 5,
 	ChannelReady = 64,
-	/// Flag which is set on ChannelReady and FundingSent indicating remote side is considered
-	/// "disconnected" and no updates are allowed until after we've done a channel_reestablish
+	/// Flag which is set on `ChannelReady` and `FundingSent` indicating remote side is considered
+	/// "disconnected" and no updates are allowed until after we've done a `channel_reestablish`
 	/// dance.
 	PeerDisconnected = 1 << 7,
-	/// Flag which is set on ChannelReady, FundingCreated, and FundingSent indicating the user has
-	/// told us a ChannelMonitor update is pending async persistence somewhere and we should pause
+	/// Flag which is set on `ChannelReady`, FundingCreated, and `FundingSent` indicating the user has
+	/// told us a `ChannelMonitor` update is pending async persistence somewhere and we should pause
 	/// sending any outbound messages until they've managed to finish.
 	MonitorUpdateInProgress = 1 << 8,
 	/// Flag which implies that we have sent a commitment_signed but are awaiting the responding
 	/// revoke_and_ack message. During this time period, we can't generate new commitment_signed
 	/// messages as then we will be unable to determine which HTLCs they included in their
 	/// revoke_and_ack implicit ACK, so instead we have to hold them away temporarily to be sent
 	/// later.
-	/// Flag is set on ChannelReady.
+	/// Flag is set on `ChannelReady`.
 	AwaitingRemoteRevoke = 1 << 9,
-	/// Flag which is set on ChannelReady or FundingSent after receiving a shutdown message from
+	/// Flag which is set on `ChannelReady` or `FundingSent` after receiving a shutdown message from
 	/// the remote end. If set, they may not add any new HTLCs to the channel, and we are expected
 	/// to respond with our own shutdown message when possible.
 	RemoteShutdownSent = 1 << 10,
-	/// Flag which is set on ChannelReady or FundingSent after sending a shutdown message. At this
+	/// Flag which is set on `ChannelReady` or `FundingSent` after sending a shutdown message. At this
 	/// point, we may not add any new HTLCs to the channel.
 	LocalShutdownSent = 1 << 11,
 	/// We've successfully negotiated a closing_signed dance. At this point ChannelManager is about
@@ -4565,9 +4565,11 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 		&self.channel_type
 	}
 
-	/// Guaranteed to be Some after both ChannelReady messages have been exchanged (and, thus,
-	/// is_usable() returns true).
+	/// Guaranteed to be [`Some`] after both [`ChannelState::ChannelReady`] messages have been exchanged
+	/// (and, thus, [`is_usable()`] returns true).
 	/// Allowed in any state (including after shutdown)
+	///
+	/// [`is_usable()`]: Self::is_usable
 	pub fn get_short_channel_id(&self) -> Option<u64> {
 		self.short_channel_id
 	}
@@ -5401,14 +5403,16 @@ impl<Signer: WriteableEcdsaChannelSigner> Channel<Signer> {
 	}
 
 	/// Gets an UnsignedChannelAnnouncement for this channel. The channel must be publicly
-	/// announceable and available for use (have exchanged ChannelReady messages in both
+	/// announceable and available for use (have exchanged [`ChannelReady`] messages in both
 	/// directions). Should be used for both broadcasted announcements and in response to an
 	/// AnnouncementSignatures message from the remote peer.
 	///
 	/// Will only fail if we're not in a state where channel_announcement may be sent (including
 	/// closing).
 	///
 	/// This will only return ChannelError::Ignore upon failure.
+	///
+	/// [`ChannelReady`]: crate::ln::msgs::ChannelReady
 	fn get_channel_announcement<NS: Deref>(
 		&self, node_signer: &NS, chain_hash: BlockHash, user_config: &UserConfig,
 	) -> Result<msgs::UnsignedChannelAnnouncement, ChannelError> where NS::Target: NodeSigner {