document mumlib

4 files changed, 76 insertions, 0 deletions

diff --git a/mumlib/src/command.rs b/mumlib/src/command.rs
index 8cb7cb9..642c8b9 100644
--- a/mumlib/src/command.rs
+++ b/mumlib/src/command.rs
@@ -1,3 +1,7 @@
+//! [Command]s can be sent from a controller to mumd who might respond with a
+//! [CommandResponse]. The commands and their responses are serializable and
+//! can be sent in any way you want.
+
 use crate::state::{Channel, Server};
 
 use chrono::NaiveDateTime;
@@ -56,29 +60,51 @@ impl fmt::Display for MumbleEventKind {
     }
 }
 
+/// Sent by a controller to mumd who might respond with a [CommandResponse]. Not
+/// all commands receive a response.
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub enum Command {
+    /// No response.
     ChannelJoin {
         channel_identifier: String,
     },
+
+    /// Response: [CommandResponse::ChannelList].
     ChannelList,
+
+    /// Force reloading of config file from disk. No response.
     ConfigReload,
+    /// Response: [CommandResponse::DeafenStatus]. Toggles if None.
     DeafenSelf(Option<bool>),
     Events {
         block: bool
     },
+    /// Set the outgoing audio volume (i.e. from you to the server). No response.
     InputVolumeSet(f32),
+
+    /// Response: [CommandResponse::MuteStatus]. Toggles if None.
     MuteOther(String, Option<bool>),
+
+    /// Response: [CommandResponse::MuteStatus]. Toggles if None.
     MuteSelf(Option<bool>),
+
+    /// Set the master incoming audio volume (i.e. from the server to you).
+    /// No response.
     OutputVolumeSet(f32),
+
     PastMessages {
         block: bool,
     },
+
+    /// Response: [CommandResponse::Pong]. Used to test existance of a
+    /// mumd-instance.
     Ping,
+
     SendMessage {
         message: String,
         targets: MessageTarget,
     },
+    /// Connect to the specified server. Response: [CommandResponse::ServerConnect].
     ServerConnect {
         host: String,
         port: u16,
@@ -86,43 +112,61 @@ pub enum Command {
         password: Option<String>,
         accept_invalid_cert: bool,
     },
+
+    /// No response.
     ServerDisconnect,
+
+    /// Send a server status request via UDP (e.g. not requiring a TCP connection).
+    /// Response: [CommandResponse::ServerStatus].
     ServerStatus {
         host: String,
         port: u16,
     },
+
+    /// Response: [CommandResponse::Status].
     Status,
+
+    /// No response.
     UserVolumeSet(String, f32),
 }
 
+/// A response to a sent [Command].
 #[derive(Debug, Deserialize, Serialize)]
 pub enum CommandResponse {
     ChannelList {
         channels: Channel,
     },
+
     DeafenStatus {
         is_deafened: bool,
     },
+
     Event {
         event: MumbleEvent,
     },
+
     MuteStatus {
         is_muted: bool,
     },
+
     PastMessage {
         message: (NaiveDateTime, String, String),
     },
+
     Pong,
+
     ServerConnect {
         welcome_message: Option<String>,
         server_state: Server,
     },
+
     ServerStatus {
         version: u32,
         users: u32,
         max_users: u32,
         bandwidth: u32,
     },
+
     Status {
         server_state: Server,
     },
diff --git a/mumlib/src/config.rs b/mumlib/src/config.rs
index 3edef37..b5bcdb1 100644
--- a/mumlib/src/config.rs
+++ b/mumlib/src/config.rs
@@ -23,6 +23,8 @@ struct TOMLConfig {
     servers: Option<Array>,
 }
 
+/// Our representation of the mumdrc config file.
+// Deserialized via [TOMLConfig].
 #[derive(Clone, Debug, Default)]
 pub struct Config {
     pub audio: AudioConfig,
@@ -34,6 +36,15 @@ pub struct Config {
 }
 
 impl Config {
+    /// Writes this config to the specified path.
+    ///
+    /// Pass create = true if you want the file to be created if it doesn't already exist.
+    ///
+    /// # Errors
+    ///
+    /// - [ConfigError::WontCreateFile] if the file doesn't exist and create = false was passed.
+    /// - Any [ConfigError::TOMLErrorSer] encountered when serializing the config.
+    /// - Any [ConfigError::IOError] encountered when writing the file.
     pub fn write(&self, path: &Path, create: bool) -> Result<(), ConfigError> {
         // Possible race here. It's fine since it shows when:
         //   1) the file doesn't exist when checked and is then created
@@ -90,6 +101,10 @@ impl ServerConfig {
     }
 }
 
+/// Finds the default path of the configuration file.
+/// 
+/// The user config dir is looked for first (cross-platform friendly) and
+/// `/etc/mumdrc` is used as a fallback.
 pub fn default_cfg_path() -> PathBuf {
     match dirs::config_dir() {
         Some(mut p) => {
@@ -143,6 +158,14 @@ impl From<Config> for TOMLConfig {
     }
 }
 
+/// Reads the config at the specified path.
+///
+/// If the file isn't found, returns a default config.
+///
+/// # Errors
+///
+/// - Any [ConfigError::TOMLErrorDe] encountered when deserializing the config.
+/// - Any [ConfigError::IOError] encountered when reading the file.
 pub fn read_cfg(path: &Path) -> Result<Config, ConfigError> {
     match fs::read_to_string(path) {
         Ok(s) => {
diff --git a/mumlib/src/lib.rs b/mumlib/src/lib.rs
index 9b7d686..4b302e3 100644
--- a/mumlib/src/lib.rs
+++ b/mumlib/src/lib.rs
@@ -9,6 +9,8 @@ use colored::*;
 use log::*;
 
 pub const SOCKET_PATH: &str = "/tmp/mumd";
+
+/// The default mumble port.
 pub const DEFAULT_PORT: u16 = 64738;
 
 pub fn setup_logger<T: Into<fern::Output>>(target: T, color: bool) {
diff --git a/mumlib/src/state.rs b/mumlib/src/state.rs
index 772e822..182a8fc 100644
--- a/mumlib/src/state.rs
+++ b/mumlib/src/state.rs
@@ -36,6 +36,9 @@ impl Channel {
             links: Vec::new(),
         }
     }
+
+    /// Create an iterator over this channel and its children in a pre-order
+    /// traversal.
     pub fn iter(&self) -> Iter<'_> {
         Iter {
             me: Some(&self),
@@ -48,6 +51,8 @@ impl Channel {
         }
     }
 
+    /// Create an iterator over this channel and its childrens connected users
+    /// in a pre-order traversal.
     pub fn users_iter(&self) -> UsersIter<'_> {
         UsersIter {
             channels: self.children.iter().map(|e| e.users_iter()).collect(),
@@ -62,6 +67,7 @@ impl Channel {
     }
 }
 
+/// An iterator over channels. Created by [Channel::iter].
 pub struct Iter<'a> {
     me: Option<&'a Channel>,
     channel: Option<usize>,
@@ -92,6 +98,7 @@ impl<'a> Iterator for Iter<'a> {
     }
 }
 
+/// An iterator over users. Created by [Channel::users_iter].
 pub struct UsersIter<'a> {
     channel: Option<usize>,
     channels: Vec<UsersIter<'a>>,