f cleanup docs a bunch

Author: TheBlueMatt

lightning/src/ln/peer_handler.rs

@@ -160,7 +160,7 @@ pub struct MessageHandler<CM: Deref, RM: Deref> where
 		CM::Target: ChannelMessageHandler,
 		RM::Target: RoutingMessageHandler {
 	/// A message handler which handles messages specific to channels. Usually this is just a
-	/// [`ChannelManager`] object or a [`ErroringMessageHandler`].
+	/// [`ChannelManager`] object or an [`ErroringMessageHandler`].
 	///
 	/// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
 	pub chan_handler: CM,
@@ -191,20 +191,22 @@ pub trait SocketDescriptor : cmp::Eq + hash::Hash + Clone {
 	/// Note that in the disconnected case, [`PeerManager::socket_disconnected`] must still be
 	/// called and further write attempts may occur until that time.
 	///
-	/// If the returned size is smaller than data.len(), a
+	/// If the returned size is smaller than `data.len()`, a
 	/// [`PeerManager::write_buffer_space_avail`] call must be made the next time more data can be
-	/// written. Additionally, until a send_data event completes fully, no further
+	/// written. Additionally, until a `send_data` event completes fully, no further
 	/// [`PeerManager::read_event`] calls should be made for the same peer! Because this is to
 	/// prevent denial-of-service issues, you should not read or buffer any data from the socket
 	/// until then.
 	///
 	/// If a [`PeerManager::read_event`] call on this descriptor had previously returned true
 	/// (indicating that read events should be paused to prevent DoS in the send buffer),
-	/// resume_read may be set indicating that read events on this descriptor should resume. A
-	/// resume_read of false does *not* imply on its own that further read events should be paused.
+	/// `resume_read` may be set indicating that read events on this descriptor should resume. A
+	/// `resume_read` of false carries no meaning, and should not cause any action.
 	fn send_data(&mut self, data: &[u8], resume_read: bool) -> usize;
 	/// Disconnect the socket pointed to by this SocketDescriptor.
-	/// No [`PeerManager::socket_disconnected`] call need be generated as a result of this call.
+	///
+	/// You do *not* need to call [`PeerManager::socket_disconnected`] with this socket after this
+	/// call (doing so is a noop).
 	fn disconnect_socket(&mut self);
 }
 
@@ -319,16 +321,16 @@ pub type SimpleArcPeerManager<SD, M, T, F, C, L> = PeerManager<SD, Arc<SimpleArc
 pub type SimpleRefPeerManager<'a, 'b, 'c, 'd, 'e, 'f, 'g, SD, M, T, F, C, L> = PeerManager<SD, SimpleRefChannelManager<'a, 'b, 'c, 'd, 'e, M, T, F, L>, &'e NetGraphMsgHandler<&'g C, &'f L>, &'f L>;
 
 /// A PeerManager manages a set of peers, described by their [`SocketDescriptor`] and marshalls
-/// socket events into messages which it passes on to its MessageHandlers.
+/// socket events into messages which it passes on to its [`MessageHandler`].
 ///
 /// Locks are taken internally, so you must never assume that reentrancy from a
 /// [`SocketDescriptor`] call back into [`PeerManager`] methods will not deadlock.
 ///
 /// Calls to [`read_event`] will decode relevant messages and pass them to the
 /// [`ChannelMessageHandler`], likely doing message processing in-line. Thus, the primary form of
-/// parallelism in Rust-Lightning is parallelism in calls to [`read_event`]. Note, however, that
-/// calls to any [`PeerManager`] functions related to the same connection must occur only in
-/// serial, making new calls only after previous ones have returned.
+/// parallelism in Rust-Lightning is in calls to [`read_event`]. Note, however, that calls to any
+/// [`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
@@ -626,11 +628,11 @@ impl<Descriptor: SocketDescriptor, CM: Deref, RM: Deref, L: Deref> PeerManager<D
 	///
 	/// May return an Err to indicate that the connection should be closed.
 	///
-	/// Will most likely call [`send_data`] on the descriptor passed in (or the descriptor handed
-	/// into new_*\_connection) 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 sufficient!
+	/// May call [`send_data`] on the descriptor passed in (or another provided 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 isnt'
+	/// sufficient!
 	///
 	/// [`send_data`]: SocketDescriptor::send_data
 	/// [`write_buffer_space_avail`]: PeerManager::write_buffer_space_avail
@@ -656,11 +658,12 @@ impl<Descriptor: SocketDescriptor, CM: Deref, RM: Deref, L: Deref> PeerManager<D
 	/// May return an Err to indicate that the connection should be closed.
 	///
 	/// Will *not* call back into [`send_data`] on any descriptors to avoid reentrancy complexity.
-	/// Thus, however, you almost certainly want to call [`process_events`] after any read_event
-	/// to generate [`send_data`] calls to handle responses.
+	/// Thus, however, you should call [`process_events`] after any `read_event` to generate
+	/// [`send_data`] calls to handle responses.
 	///
-	/// If Ok(true) is returned, further read_events should not be triggered until a [`send_data`]
-	/// call on this descriptor has resume_read set (preventing DoS issues in the send buffer).
+	/// If `Ok(true)` is returned, further read_events should not be triggered until a
+	/// [`send_data`] call on this descriptor has `resume_read` set (preventing DoS issues in the
+	/// send buffer).
 	///
 	/// [`send_data`]: SocketDescriptor::send_data
 	/// [`process_events`]: PeerManager::process_events
@@ -1113,8 +1116,8 @@ impl<Descriptor: SocketDescriptor, CM: Deref, RM: Deref, L: Deref> PeerManager<D
 	/// response messages as well as messages generated by calls to handler functions directly (eg
 	/// functions like [`ChannelManager::process_pending_htlc_forwards`] or [`send_payment`]).
 	///
-	/// Will most likely call [`send_data`] on descriptors previously provided to
-	/// new_*\_connection. Thus, be very careful with reentrancy issues!
+	/// May call [`send_data`] on [`SocketDescriptor`]s. Thus, be very careful with reentrancy
+	/// issues!
 	///
 	/// [`send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
 	/// [`ChannelManager::process_pending_htlc_forwards`]: crate::ln::channelmanager::ChannelManager::process_pending_htlc_forwards
@@ -1357,7 +1360,7 @@ impl<Descriptor: SocketDescriptor, CM: Deref, RM: Deref, L: Deref> PeerManager<D
 
 	/// Disconnect a peer given its node id.
 	///
-	/// Set no_connection_possible to true to prevent any further connection with this peer,
+	/// Set `no_connection_possible` to true to prevent any further connection with this peer,
 	/// force-closing any channels we have with it.
 	///
 	/// If a peer is connected, this will call [`disconnect_socket`] on the descriptor for the
@@ -1375,10 +1378,11 @@ impl<Descriptor: SocketDescriptor, CM: Deref, RM: Deref, L: Deref> PeerManager<D
 	}
 
 	/// This function should be called roughly once every 30 seconds.
-	/// It will send pings to each peer and disconnect those which did not respond to the last round of pings.
+	/// It will send pings to each peer and disconnect those which did not respond to the last
+	/// round of pings.
 	///
-	/// Will most likely call [`send_data`] all descriptors previously provided to
-	/// new_*\_connection. Thus, be very careful with reentrancy issues!
+	/// May call [`send_data`] all [`SocketDescriptor`]s. Thus, be very careful with reentrancy
+	/// issues!
 	///
 	/// [`send_data`]: SocketDescriptor::send_data
 	pub fn timer_tick_occurred(&self) {