Re-write CustomMessageHandler documentation

Documentation for CustomMessageHandler wasn't clear how it is related to
PeerManager and contained some grammatical and factual errors. Re-write
the docs and link to the lightning_custom_message crate.

Author: jkczyz

lightning/src/ln/peer_handler.rs

@@ -46,16 +46,23 @@ use bitcoin::hashes::sha256::Hash as Sha256;
 use bitcoin::hashes::sha256::HashEngine as Sha256Engine;
 use bitcoin::hashes::{HashEngine, Hash};
 
-/// Handler for BOLT1-compliant messages.
+/// A handler provided to [`PeerManager`] for reading and handling custom messages.
+///
+/// [BOLT 1] specifies a custom message type range for use with experimental or application-specific
+/// messages. `CustomMessageHandler` allows for user-defined handling of such types. See the
+/// [`lightning_custom_message`] crate for tools useful in composing more than one custom handler.
+///
+/// [BOLT 1]: https://github.com/lightning/bolts/blob/master/01-messaging.md
+/// [`lightning_custom_message`]: https://docs.rs/lightning_custom_message/latest/lightning_custom_message
 pub trait CustomMessageHandler: wire::CustomMessageReader {
-	/// Called with the message type that was received and the buffer to be read.
-	/// Can return a `MessageHandlingError` if the message could not be handled.
+	/// Handles the given message sent from `sender_node_id`, possibly producing messages for
+	/// [`CustomMessageHandler::get_and_clear_pending_msg`] to return and thus for [`PeerManager`]
+	/// to send.
 	fn handle_custom_message(&self, msg: Self::CustomMessage, sender_node_id: &PublicKey) -> Result<(), LightningError>;
 
-	/// Gets the list of pending messages which were generated by the custom message
-	/// handler, clearing the list in the process. The first tuple element must
-	/// correspond to the intended recipients node ids. If no connection to one of the
-	/// specified node does not exist, the message is simply not sent to it.
+	/// Returns the list of pending messages that were generated by the handler, clearing the list
+	/// in the process. Each message is paired with the node id of the intended recipient. If no
+	/// connection to the node exists, then the message is simply not sent.
 	fn get_and_clear_pending_msg(&self) -> Vec<(PublicKey, Self::CustomMessage)>;
 }