X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fln%2Fpeer_handler.rs;h=8c3ab968af20f92e3a544d7d1fea024837bd26e6;hb=9f41bd7f6492ca146a852c779f072d5b87581fed;hp=3775c27e4dff9b0c001303e1ea859b5856431d33;hpb=33720b07a06e70cef099639d054aada6bb96a3d5;p=rust-lightning

diff --git a/lightning/src/ln/peer_handler.rs b/lightning/src/ln/peer_handler.rs
index 3775c27e..8c3ab968 100644
--- a/lightning/src/ln/peer_handler.rs
+++ b/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)>;
 }