completed high level docs for mod.rs on /net module and submodules /protocols and /sessions.

src/net/acceptor.rs

@@ -10,9 +10,7 @@ use crate::system::{StoppableTask, StoppableTaskPtr, Subscriber, SubscriberPtr,
 /// Atomic pointer to Acceptor class.
 pub type AcceptorPtr = Arc<Acceptor>;
 
-/// Handles the acceptance of inbound socket connections. Used to start
-/// listening on a local socket address, to accept incoming connections and to
-/// handle network errors.
+/// Create inbound socket connections.
 pub struct Acceptor {
     channel_subscriber: SubscriberPtr<NetResult<ChannelPtr>>,
     task: StoppableTaskPtr,

src/net/channel.rs

@@ -18,11 +18,7 @@ use crate::system::{StoppableTask, StoppableTaskPtr, Subscriber, SubscriberPtr,
 /// Atomic pointer to async channel.
 pub type ChannelPtr = Arc<Channel>;
 
-/// Async channel interface that handles the sending of messages across the
-/// network. Public interface is used to create new channels, to stop and start
-/// a channel, and to send messages.
-///
-/// Implements message functionality and the message subscriber subsystem.
+/// Async channel for communication between nodes.
 pub struct Channel {
     reader: Mutex<ReadHalf<Async<TcpStream>>>,
     writer: Mutex<WriteHalf<Async<TcpStream>>>,

src/net/connector.rs

@@ -6,7 +6,7 @@ use crate::net::error::{NetError, NetResult};
 use crate::net::utility::sleep;
 use crate::net::{Channel, ChannelPtr, SettingsPtr};
 
-/// Handles the creation of outbound connections.
+/// Create outbound socket connections.
 pub struct Connector {
     settings: SettingsPtr,
 }

src/net/error.rs

@@ -3,7 +3,7 @@ use std::fmt;
 /// Returns the relevant network error if a program fails.
 pub type NetResult<T> = std::result::Result<T, NetError>;
 
-/// Defines a set of common network errors. Used for error handling.
+/// An enum representing the main network errors.
 #[derive(Debug, Copy, Clone)]
 pub enum NetError {
     OperationFailed,

src/net/message_subscriber.rs

@@ -18,8 +18,7 @@ pub type MessageSubscriptionID = u64;
 type MessageResult<M> = NetResult<Arc<M>>;
 
 /// Handles message subscriptions through a subscription ID and a receiver
-/// channel. Inherits from Message Dispatcher: a class that maintains a list of
-/// active subscribers and handles sending messages across subscriptions.
+/// channel.
 pub struct MessageSubscription<M: Message> {
     id: MessageSubscriptionID,
     recv_queue: async_channel::Receiver<MessageResult<M>>,
@@ -166,24 +165,8 @@ impl<M: Message> MessageDispatcherInterface for MessageDispatcher<M> {
     }
 }
 
-/// Generic publish/subscribe class that can dispatch any kind of message to a
-/// subscribed list of dispatchers. Dispatchers subscribe to a single
-/// message format of any type. This is a generalized version of the simple
-/// publish-subscribe class in system::Subscriber.
-///
-/// Message Subsystem also enables the creation of new message subsystems,
-/// adding new dispatchers and clearing inactive channels.
-///
-/// Message Subsystem maintains a list of dispatchers, which is a generalized
-/// version of a subscriber. Pub-sub is called on dispatchers through the
-/// functions 'subscribe' and 'notify'. Whereas system::Subscriber only allows
-/// messages of a single type, dispatchers can handle any kind of message. This
-/// generic message is called a payload and is processed and decoded by the
-/// Message Dispatcher.
-///
-/// The Message Dispatcher is a private class of subscribers that implements a
-/// generic trait called Message Dispatcher Interface. This allows us to process
-/// any kind of payload as a message.
+/// Publish/subscribe class that can dispatch any kind of message to a
+/// list of dispatchers.
 pub struct MessageSubsystem {
     dispatchers: Mutex<HashMap<&'static str, Arc<dyn MessageDispatcherInterface>>>,
 }

src/net/mod.rs

@@ -1,14 +1,94 @@
+/// Acceptor class handles the acceptance of inbound socket connections. It's
+/// used to start listening on a local socket address, to accept incoming
+/// connections and to handle network errors.
 pub mod acceptor;
+
+/// Async channel that handles the sending of messages across the network.
+/// Public interface is used to create new channels, to stop and start
+/// a channel, and to send messages.
+///
+/// Implements message functionality and the message subscriber subsystem.
 pub mod channel;
+
+/// Handles the creation of outbound connections. Used to establish an outbound
+/// connection.
 pub mod connector;
+
+/// Defines a set of common network errors. Used for error handling.
 pub mod error;
+
+/// Hosts are a list of network addresses used when establishing an outbound
+/// connection. Hosts are shared across the network through the address
+/// protocol. When attempting to connect, a node will loop through addresses in
+/// the host store until it finds ones to connect to.
 pub mod hosts;
+
+/// Generic publish/subscribe class that can dispatch any kind of message to a
+/// subscribed list of dispatchers. Dispatchers subscribe to a single
+/// message format of any type. This is a generalized version of the simple
+/// publish-subscribe class in system::Subscriber.
+///
+/// Message Subsystem also enables the creation of new message subsystems,
+/// adding new dispatchers and clearing inactive channels.
+///
+/// Message Subsystem maintains a list of dispatchers, which is a generalized
+/// version of a subscriber. Pub-sub is called on dispatchers through the
+/// functions 'subscribe' and 'notify'. Whereas system::Subscriber only allows
+/// messages of a single type, dispatchers can handle any kind of message. This
+/// generic message is called a payload and is processed and decoded by the
+/// Message Dispatcher.
+///
+/// The Message Dispatcher is a class of subscribers that implements a
+/// generic trait called Message Dispatcher Interface, which allows us to
+/// process any kind of payload as a message.
 pub mod message_subscriber;
+
+/// Defines how to decode generic messages as well as implementing the common
+/// network messages that are sent between nodes as described by the Protocol
+/// submodule.
+///
+/// Implements a type called Packet which is the base message type. Packets are
+/// converted into messages and passed to an event loop.
 pub mod messages;
+
+/// P2P provides all core functionality to interact with the peer-to-peer
+/// network.
+///
+/// Used to create a network, to start and run it, to broadcast messages across
+/// all channels, and to manage the channel store.
+///
+/// The channel store is a hashmap of channel address that we can use to add and
+/// remove channels or check whether a channel is already is in the store.
 pub mod p2p;
+
+/// Defines the networking protocol used at each stage in a connection. Consists
+/// of a series of messages that are sent across the network at the different
+/// connection stages.
+///
+/// When a node connects to a network for the first time, it must follow a seed
+/// protocol, which provides it with a list of network hosts to connect to. To
+/// establish a connection to another node, nodes must send version and version
+/// acknowledgement messages. During a connection, nodes continually get address
+/// and get-address messages to inform eachother about what nodes are on the
+/// network. Nodes also send out a ping and pong message which keeps the network
+/// from shutting down.
+///
+/// Protocol submodule also implements a jobs manager than handles the
+/// asynchronous execution of the protocols.
 pub mod protocols;
+
+/// Defines the interaction between nodes during a connection. Consists of an
+/// inbound session, which describes how to set up an incoming connection, and
+/// an outbound session, which describes setting up an outbound connection. Also
+/// describes the seed session, which is the type of connection used when a node
+/// connects to the network for the first time. Implements the session trait
+/// which describes the common functions across all sessions.
 pub mod sessions;
+
+/// Network configuration settings.
 pub mod settings;
+
+/// Utility module that defines a sleep function used throughout the network.
 pub mod utility;
 
 pub use acceptor::{Acceptor, AcceptorPtr};

src/net/p2p.rs

@@ -18,12 +18,7 @@ pub type ConnectedChannels<T> = Mutex<HashMap<SocketAddr, Arc<T>>>;
 /// Atomic pointer to p2p interface.
 pub type P2pPtr = Arc<P2p>;
 
-/// Top level peer-to-peer networking interface. Provides all core functionality
-/// to interact with the peer-to-peer network. Used to create a network, to
-/// start and run it, to broadcast messages across all channels, and to manage
-/// the channel store. The channel store is a hashmap of channel address that we
-/// can use to add and remove channels or check whether a channel is already is
-/// in the store.
+/// Top level peer-to-peer networking interface.
 pub struct P2p {
     pending: PendingChannels,
     channels: ConnectedChannels<Channel>,

src/net/protocols/mod.rs

@@ -1,7 +1,49 @@
+/// 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 mod protocol_address;
+
+/// 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 mod protocol_jobs_manager;
+
+/// 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 mod protocol_ping;
+
+/// 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 mod protocol_seed;
+
+/// Protocol for version information handshake between nodes at the start of a
+/// 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 mod protocol_version;
 
 pub use protocol_address::ProtocolAddress;

src/net/protocols/protocol_address.rs

@@ -8,15 +8,7 @@ use crate::net::messages;
 use crate::net::protocols::{ProtocolJobsManager, ProtocolJobsManagerPtr};
 use crate::net::{ChannelPtr, HostsPtr};
 
-/// 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.
+/// Defines address and get-address messages.
 pub struct ProtocolAddress {
     channel: ChannelPtr,
     addrs_sub: MessageSubscription<messages::AddrsMessage>,

src/net/protocols/protocol_ping.rs

@@ -10,16 +10,7 @@ use crate::net::protocols::{ProtocolJobsManager, ProtocolJobsManagerPtr};
 use crate::net::utility::sleep;
 use crate::net::{ChannelPtr, SettingsPtr};
 
-/// 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.
+/// Defines ping and pong messages.
 pub struct ProtocolPing {
     channel: ChannelPtr,
     settings: SettingsPtr,

src/net/protocols/protocol_seed.rs

@@ -6,13 +6,7 @@ use crate::net::error::NetResult;
 use crate::net::messages;
 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.
+/// Implements the seed protocol.
 pub struct ProtocolSeed {
     channel: ChannelPtr,
     hosts: HostsPtr,

src/net/protocols/protocol_version.rs

@@ -9,15 +9,8 @@ use crate::net::messages;
 use crate::net::utility::sleep;
 use crate::net::{ChannelPtr, SettingsPtr};
 
-/// Protocol for version information handshake between nodes at the start of a
-/// 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.
+/// Implements the protocol version handshake sent out by nodes at the beginning
+/// of a connection.
 pub struct ProtocolVersion {
     channel: ChannelPtr,
     version_sub: MessageSubscription<messages::VersionMessage>,

src/net/sessions/inbound_session.rs

@@ -10,12 +10,7 @@ use crate::net::{Acceptor, AcceptorPtr};
 use crate::net::{ChannelPtr, P2p};
 use crate::system::{StoppableTask, StoppableTaskPtr};
 
-/// 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
-/// acceptor pointer, and a stoppable task pointer. Using a weak pointer to P2P
-/// allows us to avoid circular dependencies.
+/// Defines inbound connections session.
 pub struct InboundSession {
     p2p: Weak<P2p>,
     acceptor: AcceptorPtr,

src/net/sessions/mod.rs

@@ -1,6 +1,28 @@
+/// 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
+/// acceptor pointer, and a stoppable task pointer. Using a weak pointer to P2P
+/// allows us to avoid circular dependencies.
 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
+/// 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
+/// no other part of the program uses the slots at the same time.
 pub mod outbound_session;
+
+/// 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.
 pub mod seed_session;
+
+/// Defines methods that are used across sessions. Implements registering the
+/// channel and initializing the channel by performing a network handshake.
 pub mod session;
 
 pub use inbound_session::InboundSession;

src/net/sessions/outbound_session.rs

@@ -10,14 +10,7 @@ use crate::net::sessions::Session;
 use crate::net::{ChannelPtr, Connector, P2p};
 use crate::system::{StoppableTask, StoppableTaskPtr};
 
-/// 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
-/// 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
-/// no other part of the program uses the slots at the same time.
+/// Defines outbound connections session.
 pub struct OutboundSession {
     p2p: Weak<P2p>,
     connect_slots: Mutex<Vec<StoppableTaskPtr>>,

src/net/sessions/seed_session.rs

@@ -10,9 +10,7 @@ use crate::net::sessions::Session;
 use crate::net::utility::sleep;
 use crate::net::{ChannelPtr, Connector, HostsPtr, P2p, SettingsPtr};
 
-/// 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.
+/// Defines seed connections session.
 pub struct SeedSession {
     p2p: Weak<P2p>,
 }

src/net/sessions/session.rs

@@ -26,9 +26,7 @@ async fn remove_sub_on_stop(p2p: P2pPtr, channel: ChannelPtr) {
 }
 
 #[async_trait]
-/// Session trait. Defines methods that are used across sessions. Implements
-/// registering the channel and initializing the channel by performing a network
-/// handshake.
+/// Session trait.
 pub trait Session: Sync {
     /// Registers a new channel with the session. Performs a network handshake
     /// and starts the channel.

src/net/settings.rs

@@ -4,7 +4,7 @@ use std::sync::Arc;
 /// Atomic pointer to network settings.
 pub type SettingsPtr = Arc<Settings>;
 
-/// Network configuration settings.
+/// Defines the network settings.
 #[derive(Clone)]
 pub struct Settings {
     pub inbound: Option<SocketAddr>,