From cdc5843f5d19ceee97217f3ea8d345262243032e Mon Sep 17 00:00:00 2001
From: Thelie <git.daniel@mowitz.rocks>
Date: Thu, 6 May 2021 11:35:30 +0200
Subject: [PATCH] Added doc comments to select functions.

---
 src/connect.rs | 12 +++++++++---
 src/main.rs    |  8 ++++++++
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/src/connect.rs b/src/connect.rs
index 9d8f12c..8bed2ee 100644
--- a/src/connect.rs
+++ b/src/connect.rs
@@ -15,6 +15,8 @@
  * along with Mention2Mail.  If not, see <https://www.gnu.org/licenses/>.
  */ 
 
+//! Contains utilities for connecting to an IRC server.
+
 use std::{
 	format,
 	net::TcpStream,
@@ -23,12 +25,13 @@ use irc_stream::{IrcStream, IrcRead, IrcWrite};
 use toml::value::Value;
 use native_tls::{TlsConnector,TlsStream};
 
-// Weird workaround for multitrait dyn pointer
-// https://github.com/rust-lang/rfcs/issues/2035
-// would be a charm...
+/// Workaround for multitrait dyn Box.
+/// https://github.com/rust-lang/rfcs/issues/2035
+/// would be a charm...
 pub trait IrcReadWrite: IrcRead + IrcWrite {}
 impl<T: IrcRead + IrcWrite> IrcReadWrite for T {}
 
+/// Helper function for connecting over TCP
 fn get_tcp_stream (config: &Value) 
 	-> Result<TcpStream, Box<dyn std::error::Error>> {
 	let address = format!("{}:{}",
@@ -41,6 +44,7 @@ fn get_tcp_stream (config: &Value)
 	Ok(TcpStream::connect(address)?)
 }
 
+/// Helper function for connecting over TLS
 fn get_tls_stream (config: &Value)
 	-> Result<TlsStream<TcpStream>, Box<dyn std::error::Error>> {
 	let connector = TlsConnector::new().unwrap();
@@ -52,6 +56,8 @@ fn get_tls_stream (config: &Value)
 	)
 }
 
+/// Connects to the irc server given in the config.
+/// The connection will be through either a TCP or TLS stream.
 pub fn connect_irc (config: &Value)
 	-> Result<Box<dyn IrcReadWrite>, Box<dyn std::error::Error>> {
 	
diff --git a/src/main.rs b/src/main.rs
index ec283bc..6b7f18e 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -38,6 +38,9 @@ use toml::value::Value;
 trait IrcReadWrite: IrcRead + IrcWrite {}
 impl<T: IrcRead + IrcWrite> IrcReadWrite for T {}
 
+/// parses a toml config file and sets some default values
+/// if the corresponding fields are not set.
+// TODO: Document config file options once they are stable.
 fn get_config<P: AsRef<Path>>(config_path: P) 
 	-> Result<Value, Box<dyn std::error::Error>> {
 	
@@ -68,6 +71,9 @@ fn get_config<P: AsRef<Path>>(config_path: P)
 	Ok(Value::from(config))
 }
 
+/// Constructs a VecDeque with the messages
+/// required to identify with an IRC server.
+/// Uses the credentials set in -`config.toml`.
 fn get_irc_identify_messages (config: &Value) 
 	-> Result<VecDeque<Message>, Box<dyn std::error::Error>> {	
 	let mut queue = VecDeque::new();
@@ -115,6 +121,8 @@ fn get_irc_identify_messages (config: &Value)
 	Ok(queue)
 }
 
+/// Appends a given VecDeque to include the messages
+/// used to join the channels defined in `config.toml`.
 fn get_irc_join_messages(config: &Value, queue: VecDeque<Message>)
 	-> Result<VecDeque<Message>, Box<dyn std::error::Error>> {
 	let mut queue = queue;