Merge pull request #2100 from douglaz/docs_fixes

Docs improvements

Author: TheBlueMatt

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/channelmanager.rs

@@ -7,19 +7,7 @@
 // You may not use this file except in accordance with one or both of these
 // licenses.
 
-//! High level lightning structs and impls live here.
-//!
-//! You probably want to create a [`ChannelManager`], and a [`P2PGossipSync`] first.
-//! Then, you probably want to pass them both on to a peer_handler::PeerManager and use that to
-//! create/manage connections and call get_and_clear_pending_events after each action, handling
-//! them appropriately.
-//!
-//! When you want to open/close a channel or send a payment, call into your [`ChannelManager`] and
-//! when you want to learn things about the network topology (eg get a route for sending a payment),
-//! call into your [`P2PGossipSync`].
-//!
-//! [`ChannelManager`]: channelmanager::ChannelManager
-//! [`P2PGossipSync`]: crate::routing::gossip::P2PGossipSync
+//! Implementations of various parts of the Lightning protocol are in this module.
 
 #[cfg(any(test, feature = "_test_utils"))]
 #[macro_use]

lightning/src/ln/mod.rs

@@ -284,7 +284,7 @@ pub struct MessageHandler<CM: Deref, RM: Deref, OM: Deref> where
 /// to a remote host. You will need to be able to generate multiple of these which meet Eq and
 /// implement Hash to meet the PeerManager API.
 ///
-/// For efficiency, Clone should be relatively cheap for this type.
+/// For efficiency, [`Clone`] should be relatively cheap for this type.
 ///
 /// Two descriptors may compare equal (by [`cmp::Eq`] and [`hash::Hash`]) as long as the original
 /// has been disconnected, the [`PeerManager`] has been informed of the disconnection (either by it
@@ -547,10 +547,10 @@ pub type SimpleRefPeerManager<'a, 'b, 'c, 'd, 'e, 'f, 'g, 'h, 'i, 'j, 'k, 'l, 'm
 /// [`PeerManager`] functions related to the same connection must occur only in serial, making new
 /// calls only after previous ones have returned.
 ///
-/// Rather than using a plain PeerManager, it is preferable to use either a SimpleArcPeerManager
-/// a SimpleRefPeerManager, for conciseness. See their documentation for more details, but
-/// essentially you should default to using a SimpleRefPeerManager, and use a
-/// SimpleArcPeerManager when you require a PeerManager with a static lifetime, such as when
+/// Rather than using a plain [`PeerManager`], it is preferable to use either a [`SimpleArcPeerManager`]
+/// a [`SimpleRefPeerManager`], for conciseness. See their documentation for more details, but
+/// essentially you should default to using a [`SimpleRefPeerManager`], and use a
+/// [`SimpleArcPeerManager`] when you require a `PeerManager` with a static lifetime, such as when
 /// you're using lightning-net-tokio.
 ///
 /// [`read_event`]: PeerManager::read_event
@@ -638,7 +638,7 @@ impl<Descriptor: SocketDescriptor, CM: Deref, OM: Deref, L: Deref, NS: Deref> Pe
 	/// `OnionMessageHandler`. No routing message handler is used and network graph messages are
 	/// ignored.
 	///
-	/// ephemeral_random_data is used to derive per-connection ephemeral keys and must be
+	/// `ephemeral_random_data` is used to derive per-connection ephemeral keys and must be
 	/// cryptographically secure random bytes.
 	///
 	/// `current_time` is used as an always-increasing counter that survives across restarts and is
@@ -670,7 +670,7 @@ impl<Descriptor: SocketDescriptor, RM: Deref, L: Deref, NS: Deref> PeerManager<D
 	/// timestamp, however if it is not available a persistent counter that increases once per
 	/// minute should suffice.
 	///
-	/// ephemeral_random_data is used to derive per-connection ephemeral keys and must be
+	/// `ephemeral_random_data` is used to derive per-connection ephemeral keys and must be
 	/// cryptographically secure random bytes.
 	///
 	/// (C-not exported) as we can't export a PeerManager with a dummy channel handler
@@ -732,8 +732,9 @@ impl<Descriptor: SocketDescriptor, CM: Deref, RM: Deref, OM: Deref, L: Deref, CM
 		CMH::Target: CustomMessageHandler,
 		NS::Target: NodeSigner
 {
-	/// Constructs a new PeerManager with the given message handlers and node_id secret key
-	/// ephemeral_random_data is used to derive per-connection ephemeral keys and must be
+	/// Constructs a new `PeerManager` with the given message handlers.
+	///
+	/// `ephemeral_random_data` is used to derive per-connection ephemeral keys and must be
 	/// cryptographically secure random bytes.
 	///
 	/// `current_time` is used as an always-increasing counter that survives across restarts and is
@@ -806,9 +807,9 @@ impl<Descriptor: SocketDescriptor, CM: Deref, RM: Deref, OM: Deref, L: Deref, CM
 	/// Returns a small number of bytes to send to the remote node (currently always 50).
 	///
 	/// Panics if descriptor is duplicative with some other descriptor which has not yet been
-	/// [`socket_disconnected()`].
+	/// [`socket_disconnected`].
 	///
-	/// [`socket_disconnected()`]: PeerManager::socket_disconnected
+	/// [`socket_disconnected`]: PeerManager::socket_disconnected
 	pub fn new_outbound_connection(&self, their_node_id: PublicKey, descriptor: Descriptor, remote_network_address: Option<NetAddress>) -> Result<Vec<u8>, PeerHandleError> {
 		let mut peer_encryptor = PeerChannelEncryptor::new_outbound(their_node_id.clone(), self.get_ephemeral_key());
 		let res = peer_encryptor.get_act_one(&self.secp_ctx).to_vec();
@@ -863,9 +864,9 @@ impl<Descriptor: SocketDescriptor, CM: Deref, RM: Deref, OM: Deref, L: Deref, CM
 	/// the connection immediately.
 	///
 	/// Panics if descriptor is duplicative with some other descriptor which has not yet been
-	/// [`socket_disconnected()`].
+	/// [`socket_disconnected`].
 	///
-	/// [`socket_disconnected()`]: PeerManager::socket_disconnected
+	/// [`socket_disconnected`]: PeerManager::socket_disconnected
 	pub fn new_inbound_connection(&self, descriptor: Descriptor, remote_network_address: Option<NetAddress>) -> Result<(), PeerHandleError> {
 		let peer_encryptor = PeerChannelEncryptor::new_inbound(&self.node_signer);
 		let pending_read_buffer = [0; 50].to_vec(); // Noise act one is 50 bytes
@@ -1011,7 +1012,7 @@ impl<Descriptor: SocketDescriptor, CM: Deref, RM: Deref, OM: Deref, L: Deref, CM
 	/// May call [`send_data`] on the descriptor passed in (or an equal descriptor) before
 	/// returning. Thus, be very careful with reentrancy issues! The invariants around calling
 	/// [`write_buffer_space_avail`] in case a write did not fully complete must still hold - be
-	/// ready to call `[write_buffer_space_avail`] again if a write call generated here isn't
+	/// ready to call [`write_buffer_space_avail`] again if a write call generated here isn't
 	/// sufficient!
 	///
 	/// [`send_data`]: SocketDescriptor::send_data

lightning/src/ln/peer_handler.rs

@@ -42,7 +42,7 @@ pub(crate) trait TestEq {}
 impl<T> TestEq for T {}
 
 
-/// A Lightning message returned by [`read()`] when decoding bytes received over the wire. Each
+/// A Lightning message returned by [`read`] when decoding bytes received over the wire. Each
 /// variant contains a message from [`msgs`] or otherwise the message type if unknown.
 #[allow(missing_docs)]
 #[derive(Debug)]

lightning/src/ln/wire.rs

@@ -234,7 +234,7 @@ impl<G: Deref<Target=NetworkGraph<L>>, U: Deref, L: Deref> P2PGossipSync<G, U, L
 where U::Target: UtxoLookup, L::Target: Logger
 {
 	/// Creates a new tracker of the actual state of the network of channels and nodes,
-	/// assuming an existing Network Graph.
+	/// assuming an existing [`NetworkGraph`].
 	/// UTXO lookup is used to make sure announced channels exist on-chain, channel data is
 	/// correct, and the announcement is signed with channel owners' keys.
 	pub fn new(network_graph: G, utxo_lookup: Option<U>, logger: L) -> Self {
@@ -432,14 +432,20 @@ where U::Target: UtxoLookup, L::Target: Logger
 	}
 
 	/// Initiates a stateless sync of routing gossip information with a peer
-	/// using gossip_queries. The default strategy used by this implementation
+	/// using [`gossip_queries`]. The default strategy used by this implementation
 	/// is to sync the full block range with several peers.
 	///
-	/// We should expect one or more reply_channel_range messages in response
-	/// to our query_channel_range. Each reply will enqueue a query_scid message
+	/// We should expect one or more [`reply_channel_range`] messages in response
+	/// to our [`query_channel_range`]. Each reply will enqueue a [`query_scid`] message
 	/// to request gossip messages for each channel. The sync is considered complete
-	/// when the final reply_scids_end message is received, though we are not
+	/// when the final [`reply_scids_end`] message is received, though we are not
 	/// tracking this directly.
+	///
+	/// [`gossip_queries`]: https://github.com/lightning/bolts/blob/master/07-routing-gossip.md#query-messages
+	/// [`reply_channel_range`]: msgs::ReplyChannelRange
+	/// [`query_channel_range`]: msgs::QueryChannelRange
+	/// [`query_scid`]: msgs::QueryShortChannelIds
+	/// [`reply_scids_end`]: msgs::ReplyShortChannelIdsEnd
 	fn peer_connected(&self, their_node_id: &PublicKey, init_msg: &Init, _inbound: bool) -> Result<(), ()> {
 		// We will only perform a sync with peers that support gossip_queries.
 		if !init_msg.features.supports_gossip_queries() {