more verbose doc on each protocol. explains the role of each protocol in a network connection.

src/net/protocols/protocol_address.rs

@@ -8,15 +8,20 @@ use crate::net::messages;
 use crate::net::protocols::{ProtocolJobsManager, ProtocolJobsManagerPtr};
 use crate::net::{ChannelPtr, HostsPtr};
 
-/// Protocol for address and get-address messages.
+/// Protocol for address and get-address messages. Implements how nodes exchange
+/// connection information about other nodes on the network. Address and
+/// get-address messages are exchanged continually alongside ping-pong messages
+/// as part of a network connection.
+///
+/// Protocol starts by creating a subscription to address and get address
+/// messages. Then the protocol sends out a get address message and waits for an
+/// address message. Upon receiving an address messages, nodes add the
+/// address information to their local store.
 pub struct ProtocolAddress {
     channel: ChannelPtr,
-
     addrs_sub: MessageSubscription<messages::AddrsMessage>,
     get_addrs_sub: MessageSubscription<messages::GetAddrsMessage>,
-
     hosts: HostsPtr,
-
     jobsman: ProtocolJobsManagerPtr,
 }
 

src/net/protocols/protocol_jobs_manager.rs

@@ -11,7 +11,9 @@ use crate::system::ExecutorPtr;
 /// Pointer to protocol jobs manager.
 pub type ProtocolJobsManagerPtr = Arc<ProtocolJobsManager>;
 
-/// Manages the tasks for the network protocol.
+/// Manages the tasks for the network protocol. Used by other connection
+/// protocols to handle asynchronous task execution across the network. Runs all
+/// tasks that are handed to it on an executor that has stopping functionality.
 pub struct ProtocolJobsManager {
     name: &'static str,
     channel: ChannelPtr,

src/net/protocols/protocol_ping.rs

@@ -10,11 +10,19 @@ use crate::net::protocols::{ProtocolJobsManager, ProtocolJobsManagerPtr};
 use crate::net::utility::sleep;
 use crate::net::{ChannelPtr, SettingsPtr};
 
-/// Protocol for ping-pong keep-alive messages.
+/// Protocol for ping-pong keep-alive messages. Implements ping message and pong
+/// response. These messages are like the network heartbeat- they are sent
+/// continually between nodes, to ensure each node is still alive and active.
+/// Ping-pong messages ensure that the network doesn't
+/// time out.
+///
+/// Protocol starts by creating a subscription to ping and pong messages. Then
+/// it starts a loop with a timer and runs ping-pong in the task manager. It
+/// sends out a ping and waits for pong reply. Then waits for ping and replies
+/// with a pong.
 pub struct ProtocolPing {
     channel: ChannelPtr,
     settings: SettingsPtr,
-
     jobsman: ProtocolJobsManagerPtr,
 }
 

src/net/protocols/protocol_seed.rs

@@ -8,6 +8,11 @@ use crate::net::{ChannelPtr, HostsPtr, SettingsPtr};
 
 /// Seed server protocol. Seed server is used when connecting to the network for
 /// the first time. Returns a list of IP addresses that nodes can connect to.
+///
+/// To start the seed protocol, we create a subscription to the address message,
+/// and send our address to the seed server. Then we send a get-address message
+/// and receive an address message. We add these addresses to our internal
+/// store.
 pub struct ProtocolSeed {
     channel: ChannelPtr,
     hosts: HostsPtr,

src/net/protocols/protocol_version.rs

@@ -10,7 +10,14 @@ use crate::net::utility::sleep;
 use crate::net::{ChannelPtr, SettingsPtr};
 
 /// Protocol for version information handshake between nodes at the start of a
-/// connection.
+/// connection. Implements the process for exchanging version information
+/// between nodes. This is the first step when establishing a p2p connection.
+///
+/// The version protocol starts of by instantiating the protocol and creating a
+/// new subscription to version and version acknowledgement messages. Then we
+/// run the protocol. Nodes send a version message and wait for a version
+/// acknowledgement, while asynchronously waiting for version info from the
+/// other node and sending the version acknowledgement.
 pub struct ProtocolVersion {
     channel: ChannelPtr,
     version_sub: MessageSubscription<messages::VersionMessage>,