From ed4b641f6d4816325aa07e0f13b6132c1c4dafa2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gustav=20S=C3=B6rn=C3=A4s?= <gustav@sornas.net>
Date: Tue, 15 Jun 2021 12:50:01 +0200
Subject: more mumlib doc just because

---
 mumlib/src/command.rs |  8 ++++++++
 mumlib/src/config.rs  | 33 ++++++++++++++++++++++++++-------
 mumlib/src/lib.rs     |  8 ++++++++
 3 files changed, 42 insertions(+), 7 deletions(-)

(limited to 'mumlib')

diff --git a/mumlib/src/command.rs b/mumlib/src/command.rs
index 642c8b9..3c56130 100644
--- a/mumlib/src/command.rs
+++ b/mumlib/src/command.rs
@@ -11,7 +11,9 @@ use std::fmt;
 /// Something that happened in our channel at a point in time.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct MumbleEvent {
+    /// When the event occured.
     pub timestamp: NaiveDateTime,
+    /// What occured.
     pub kind: MumbleEventKind
 }
 
@@ -24,11 +26,17 @@ impl fmt::Display for MumbleEvent {
 /// The different kinds of events that can happen.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum MumbleEventKind {
+    /// A user connected to the server and joined our channel. Contains `(user, channel)`.
     UserConnected(String, String),
+    /// A user disconnected from the server while in our channel. Contains `(user, channel)`.
     UserDisconnected(String, String),
+    /// A user {un,}{muted,deafened}. Contains a rendered message with what changed and the user.
     UserMuteStateChanged(String),  // This logic is kinda weird so we only store the rendered message.
+    /// A text message was received. Contains who sent the message.
     TextMessageReceived(String),
+    /// A user switched to our channel from some other channel. Contains `(user, previous-channel)`.
     UserJoinedChannel(String, String),
+    /// A user switched from our channel to some other channel. Contains `(user, new-channel)`.
     UserLeftChannel(String, String),
 }
 
diff --git a/mumlib/src/config.rs b/mumlib/src/config.rs
index b5bcdb1..932e013 100644
--- a/mumlib/src/config.rs
+++ b/mumlib/src/config.rs
@@ -1,3 +1,5 @@
+//! Representations of the mumdrc configuration file.
+
 use crate::error::ConfigError;
 use crate::DEFAULT_PORT;
 
@@ -27,7 +29,9 @@ struct TOMLConfig {
 // Deserialized via [TOMLConfig].
 #[derive(Clone, Debug, Default)]
 pub struct Config {
+    /// General audio configuration.
     pub audio: AudioConfig,
+    /// Saved servers.
     pub servers: Vec<ServerConfig>,
     /// Whether we allow connecting to servers with invalid server certificates.
     ///
@@ -66,38 +70,53 @@ impl Config {
     }
 }
 
+/// Overwrite a specific sound effect with a file that should be played instead.
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 pub struct SoundEffect {
+    /// During which event the effect should be played.
     pub event: String,
+    /// The file that should be played.
     pub file: String,
 }
 
+/// General audio configuration.
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 pub struct AudioConfig {
+    /// The microphone input sensitivity.
     pub input_volume: Option<f32>,
+    /// The output main gain.
     pub output_volume: Option<f32>,
+    /// Overriden sound effects.
     pub sound_effects: Option<Vec<SoundEffect>>,
 }
 
+/// A saved server.
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct ServerConfig {
+    /// The alias of the server.
     pub name: String,
+    /// The host (URL or IP-adress) of the server.
     pub host: String,
+    /// The port, if non-default.
     pub port: Option<u16>,
+    /// The username to connect with. Prompted on connection if omitted.
     pub username: Option<String>,
+    /// The password to connect with. Nothing is sent to the server if omitted.
     pub password: Option<String>,
+    /// Whether to accept invalid server certifications for this server.
     pub accept_invalid_cert: Option<bool>,
 }
 
 impl ServerConfig {
+    /// Creates a [SocketAddr] for this server.
+    /// 
+    /// Returns `None` if no resolution could be made. See
+    /// [std::net::ToSocketAddrs] for more information.
     pub fn to_socket_addr(&self) -> Option<SocketAddr> {
-        match (self.host.as_str(), self.port.unwrap_or(DEFAULT_PORT))
-            .to_socket_addrs()
-            .map(|mut e| e.next())
-        {
-            Ok(Some(addr)) => Some(addr),
-            _ => None,
-        }
+        Some((self.host.as_str(), self.port.unwrap_or(DEFAULT_PORT))
+                .to_socket_addrs()
+                .ok()?
+                .next()?)
     }
 }
 
diff --git a/mumlib/src/lib.rs b/mumlib/src/lib.rs
index 4b302e3..679db8d 100644
--- a/mumlib/src/lib.rs
+++ b/mumlib/src/lib.rs
@@ -1,3 +1,7 @@
+//! Shared items for crates that want to communicate with mumd and/or mumctl.
+
+// #![warn(missing_docs)]
+
 pub mod command;
 pub mod config;
 pub mod error;
@@ -8,11 +12,15 @@ pub use error::Error;
 use colored::*;
 use log::*;
 
+/// The default file path to use for the socket.
 pub const SOCKET_PATH: &str = "/tmp/mumd";
 
 /// The default mumble port.
 pub const DEFAULT_PORT: u16 = 64738;
 
+/// Setup a minimal fern logger.
+///
+/// Format: `LEVEL [yyyy-mm-dd][HH:MM:SS] FILE:LINE MESSAGE`
 pub fn setup_logger<T: Into<fern::Output>>(target: T, color: bool) {
     fern::Dispatch::new()
         .format(move |out, message, record| {
-- 
cgit v1.2.1