From b890e1dc5ffa137bc53ae2ce3a0c8c18ef3a0087 Mon Sep 17 00:00:00 2001
From: rachel-rose <ihateface@autistici.org>
Date: Mon, 5 Apr 2021 12:44:29 +0200
Subject: [PATCH] edited documentation on session components to be more verbose
 and descriptive

---
 src/net/sessions/inbound_session.rs  |  7 ++++++-
 src/net/sessions/outbound_session.rs | 10 +++++++++-
 src/net/sessions/seed_session.rs     |  4 +++-
 3 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/src/net/sessions/inbound_session.rs b/src/net/sessions/inbound_session.rs
index c2b50e5e8..dd2920bf9 100644
--- a/src/net/sessions/inbound_session.rs
+++ b/src/net/sessions/inbound_session.rs
@@ -10,7 +10,12 @@ use crate::net::{Acceptor, AcceptorPtr};
 use crate::net::{ChannelPtr, P2p};
 use crate::system::{StoppableTask, StoppableTaskPtr};
 
-/// Inbound connections 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
+/// acceptor pointer, and a stoppable task pointer. Using a weak pointer to P2P
+/// allows us to avoid circular dependencies.
 pub struct InboundSession {
     p2p: Weak<P2p>,
     acceptor: AcceptorPtr,
diff --git a/src/net/sessions/outbound_session.rs b/src/net/sessions/outbound_session.rs
index 77c205b34..f38f2fb0e 100644
--- a/src/net/sessions/outbound_session.rs
+++ b/src/net/sessions/outbound_session.rs
@@ -10,7 +10,14 @@ use crate::net::sessions::Session;
 use crate::net::{ChannelPtr, Connector, P2p};
 use crate::system::{StoppableTask, StoppableTaskPtr};
 
-/// Outbound connections 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 struct OutboundSession {
     p2p: Weak<P2p>,
     connect_slots: Mutex<Vec<StoppableTaskPtr>>,
@@ -28,6 +35,7 @@ impl OutboundSession {
     pub async fn start(self: Arc<Self>, executor: Arc<Executor<'_>>) -> NetResult<()> {
         let slots_count = self.p2p().settings().outbound_connections;
         info!("Starting {} outbound connection slots.", slots_count);
+        // Activate mutex lock on connection slots.
         let mut connect_slots = self.connect_slots.lock().await;
 
         for i in 0..slots_count {
diff --git a/src/net/sessions/seed_session.rs b/src/net/sessions/seed_session.rs
index 2f1c4c74c..29394ba97 100644
--- a/src/net/sessions/seed_session.rs
+++ b/src/net/sessions/seed_session.rs
@@ -10,7 +10,9 @@ use crate::net::sessions::Session;
 use crate::net::utility::sleep;
 use crate::net::{ChannelPtr, Connector, HostsPtr, P2p, SettingsPtr};
 
-/// Seed connections 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 struct SeedSession {
     p2p: Weak<P2p>,
 }