net: improve some documentation and correct errors

src/net/p2p.rs

@@ -73,8 +73,13 @@ pub struct P2p {
 }
 
 impl P2p {
-    // TODO: documentation is unclear
-    /// Create a new p2p network.
+    /// Initialize a new p2p network.
+    ///
+    /// Initializes all sessions and protocols. Adds the protocols to the protocol registry, along
+    /// with a bitflag session selector that includes or excludes sessions from seed, version, and
+    /// address protocols.
+    ///
+    /// Creates a weak pointer to self that is used by all sessions to access the p2p parent class.
     pub async fn new(settings: Settings) -> Arc<Self> {
         let settings = Arc::new(settings);
 
@@ -147,9 +152,8 @@ impl P2p {
         self.session_outbound.lock().await.as_ref().unwrap().clone()
     }
 
-    // TODO: this documentation is wrong
-    /// Synchronize the blockchain and then begin long running sessions,
-    /// call after start() is invoked.
+    /// Runs the network. Starts inbound, outbound and manual sessions.
+    /// Waits for a stop signal and stops the network if received.
     pub async fn run(self: Arc<Self>, executor: Arc<Executor<'_>>) -> Result<()> {
         debug!(target: "net", "P2p::run() [BEGIN]");
 

src/net/session/mod.rs

@@ -8,9 +8,26 @@ use crate::Result;
 
 use super::{p2p::P2pPtr, protocol::ProtocolVersion, ChannelPtr};
 
-/// Seed connections session. Manages the creation of seed sessions. Used on
-/// first time connecting to the network. The seed node stores a list of other
-/// nodes in the network.
+/// Seed session creates a connection to the seed nodes specified in settings.
+/// A new seed session is created every time we call p2p::start(). The seed
+/// session loops through all the configured seeds and tries to connect to
+/// them using a Connector. The seed session either connects successfully,
+/// fails with an error or times out.
+///
+/// If a seed node connects successfully, it runs a version exchange protocol,
+/// stores the channel in the p2p list of channels, and disconnects, removing
+/// the channel from the channel list.
+///
+/// The channel is registered using Session trait method, register_channel().
+/// This invokes the Protocol Registry method attach(). Usually this returns a
+/// list of protocols that we loop through and start. In this case, attach()
+/// uses the bitflag selector to identify seed sessions and exclude them.
+///
+/// The version exchange occurs inside register_channel(). We create a handshake
+/// task that runs the version exchange with the function
+/// perform_handshake_protocols(). This runs the version exchange protocol,
+/// stores the channel in the p2p list of channels, and subscribes to a stop
+/// signal.
 pub mod seed_session;
 
 pub mod manual_session;
@@ -18,7 +35,7 @@ pub mod manual_session;
 /// Inbound connections session. Manages the creation of inbound sessions. Used
 /// to create an inbound session and start and stop the session.
 ///
-/// Class consists of 3 pointers: a weak pointer to the peer-to-peer class, an
+/// Class consists of 3 pointers: a weak pointer to the p2p parent class, an
 /// acceptor pointer, and a stoppable task pointer. Using a weak pointer to P2P
 /// allows us to avoid circular dependencies.
 pub mod inbound_session;
@@ -26,7 +43,7 @@ pub mod inbound_session;
 /// Outbound connections session. Manages the creation of outbound sessions.
 /// Used to create an outbound session and stop and start the session.
 ///
-/// Class consists of a weak pointer to the peer-to-peer interface and a vector
+/// Class consists of a weak pointer to the p2p interface and a vector
 /// of outbound connection slots. Using a weak pointer to p2p allows us to avoid
 /// circular dependencies. The vector of slots is wrapped in a mutex lock. This
 /// is switched on everytime we instantiate a connection slot and insures that

src/net/session/seed_session.rs

@@ -89,9 +89,7 @@ impl SeedSession {
         Ok(())
     }
 
-    /// Connects to a seed socket address. Registers a new channel with a
-    /// network handshake, then starts the keep-alive messages and seed
-    /// protocol.
+    /// Connects to a seed socket address.
     async fn start_seed(
         self: Arc<Self>,
         seed_index: usize,

src/net/settings.rs

@@ -8,8 +8,7 @@ use url::Url;
 /// Atomic pointer to network settings.
 pub type SettingsPtr = Arc<Settings>;
 
-// TODO: better documentation
-/// Defines the network settings.
+/// Default settings for the network. Can be manually configured.
 #[derive(Clone, Debug)]
 pub struct Settings {
     pub inbound: Option<Url>,