chore: comment more stuff

uxi/src/context.rs

@@ -1,8 +1,21 @@
+// Copyright © 2024 Rak Laptudirm <rak@laptudirm.com>
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex, MutexGuard};
+
 use crate::{flag, parameter, BundledCtx, Parameter};
-use std::{
-    collections::HashMap,
-    sync::{Arc, Mutex, MutexGuard},
-};
+
 /// Bundle is a packet containing all the relevant context necessary for a
 /// [Command](crate::Command) invocation. It provides access to the values of
 /// the flags provided to the command during invocation, the user specific
@@ -65,18 +78,25 @@ pub type GuardedBundledCtx<T> = Arc<Mutex<BundledCtx<T>>>;
 
 #[derive(Clone)]
 pub struct Context {
-    pub protocol: String,
-
+    /// The name of this Client's engine.
     pub engine: String,
+    /// The author of this Client's engine.
     pub author: String,
 
+    /// The UXI protocol supported by this Client.
+    pub protocol: String,
+    /// The currently selected protocol. It can have the values "" for when no uxi
+    /// command has been received, "ugi", or <protocol> for those protocols.
     pub selected_protocol: String,
 
+    /// Schema of the options supported by this Client.
     pub options: HashMap<String, Parameter>,
+    /// Values of the options supported by this Client.
     pub option_values: parameter::Values,
 }
 
 impl Context {
+    /// setoption sets the value of the given option to the given value.
     pub fn setoption(&mut self, name: &str, value: &str) -> Result<(), String> {
         let option = self.options.get(name);
         if option.is_none() {
@@ -91,9 +111,9 @@ impl Context {
 impl Default for Context {
     fn default() -> Self {
         Context {
-            protocol: "".to_string(),
             engine: "Nameless v0.0.0".to_string(),
             author: "Anonymous".to_string(),
+            protocol: "".to_string(),
             selected_protocol: "".to_string(),
             options: HashMap::new(),
             option_values: Default::default(),

uxi/src/flag.rs

@@ -70,6 +70,8 @@ impl Values {
 }
 
 impl Values {
+    /// insert adds the given [Flag] with the given value to the current flag
+    /// value set which will be provided to the Command's run function.
     pub fn insert(&mut self, name: &str, flag: Flag, value: &[&str]) {
         let name = name.to_string();
         let value = Vec::from_iter(value.iter().map(|s| s.to_string()));

uxi/src/inbuilt.rs

@@ -14,38 +14,49 @@
 use std::ops::{Deref, DerefMut};
 use std::sync::{Arc, Mutex};
 
-use crate::{context::Context, GuardedBundledCtx, Number};
+use crate::{context::Context, GuardedBundledCtx};
 
 /// A BundledCtx bundles the user-provided context `C` and the inbuilt context
-/// into a single type of ease of mutex guarding for concurrency.
-pub struct BundledCtx<T: Send> {
-    user: T,
+/// into a single type of ease of mutex guarding for concurrency. It provides
+/// methods which allow Commands to retrieve information from those contexts.
+pub struct BundledCtx<C: Send> {
+    user: C,
     client: Context,
 }
 
-pub fn new_guarded_ctx<T: Send>(user: T, client: Context) -> GuardedBundledCtx<T> {
+/// new_guarded_ctx created a new [GuardedBundledCtx] from the given user and
+/// client contexts.
+pub fn new_guarded_ctx<C: Send>(user: C, client: Context) -> GuardedBundledCtx<C> {
     Arc::new(Mutex::new(BundledCtx { user, client }))
 }
 
 impl<T: Send> BundledCtx<T> {
+    /// protocol returns the last protocol command which was issues to the Client.
+    /// It returns "" if no protocol command has been issued to the engine till now.
     pub fn protocol(&self) -> String {
         self.client.selected_protocol.clone()
     }
 
+    /// get_check_option returns the value of a check option with the given name.
     pub fn get_check_option(&self, name: &str) -> Option<bool> {
         self.client.option_values.get_check(name)
     }
 
+    /// get_string_option returns the value of a combo/string option with the given
+    /// name.
     pub fn get_string_option(&self, name: &str) -> Option<String> {
         self.client.option_values.get_string(name)
     }
 
-    pub fn get_spin_option(&self, name: &str) -> Option<Number> {
+    /// get_spin_option returns the value of a spin option with the given name.
+    pub fn get_spin_option(&self, name: &str) -> Option<i64> {
         self.client.option_values.get_spin(name)
     }
 }
 
 impl<T: Send> Deref for BundledCtx<T> {
+    /// A BundledCtx can be dereferenced into the user's context and freely
+    /// manipulated. This is because both Deref and DerefMut are implemented.
     type Target = T;
 
     fn deref(&self) -> &Self::Target {
@@ -59,26 +70,34 @@ impl<T: Send> DerefMut for BundledCtx<T> {
     }
 }
 
+/// The commands module contains functions which resolve into one of the inbuilt
+/// Commands which come pre-registered with the Client.
 pub mod commands {
-    use crate::{context::Context, error, quit, Command, Flag, Parameter, RunError};
+    use crate::context::Context;
+    use crate::{error, quit, Command, Flag, Parameter, RunError};
 
+    /// quit resolves into the quit Command which quits the Client.
     pub fn quit<C: Send>() -> Command<C> {
         Command::new(|_ctx| quit!())
     }
 
+    /// isready resolves into the isready command which is used to ping the Client
+    /// and check for responsiveness, i.e. if its ready for the next Command.
     pub fn isready<C: Send>() -> Command<C> {
         Command::new(|_ctx| {
             println!("readyok");
             Ok(())
         })
     }
 
+    /// uxi resolves into one of the uxi commands which respond with information
+    /// about the Client and 'uxiok' to show support for that UXI protocol.
     pub fn uxi<C: Send>() -> Command<C> {
         #[allow(clippy::assigning_clones)]
         Command::new(|ctx| {
             let mut ctx = ctx.lock();
 
-            print_protocol_info(&ctx.client);
+            print_client_info(&ctx.client);
             println!("{}ok", ctx.client.protocol);
 
             ctx.client.selected_protocol = ctx.client.protocol.clone();
@@ -87,11 +106,12 @@ pub mod commands {
         })
     }
 
+    /// ugi is similar to the uxi Command, just for the UGI protocol.
     pub fn ugi<C: Send>() -> Command<C> {
         Command::new(|ctx| {
             let mut ctx = ctx.lock();
 
-            print_protocol_info(&ctx.client);
+            print_client_info(&ctx.client);
             println!("ugiok");
 
             ctx.client.selected_protocol = "ugi".to_string();
@@ -100,7 +120,9 @@ pub mod commands {
         })
     }
 
-    fn print_protocol_info(ctx: &Context) {
+    /// print_client_info prints information about the Client, which is reported in
+    /// response to a uxi type protocol command.
+    fn print_client_info(ctx: &Context) {
         println!("id name {}", ctx.engine);
         println!("id author {}", ctx.author);
         println!();
@@ -113,6 +135,8 @@ pub mod commands {
         }
     }
 
+    /// setoption is the Command to set the values of the different
+    /// [options](Parameter) supported by the Client.
     pub fn setoption<C: Send>() -> Command<C> {
         Command::new(|ctx| {
             let name = ctx.get_single_flag("name");
@@ -133,6 +157,8 @@ pub mod commands {
         .flag("value", Flag::Variadic)
     }
 
+    /// options lists the [options](Parameter) supported by the Client and their
+    /// currently set values. This command is not part of the UXI standard.
     pub fn options<C: Send>() -> Command<C> {
         Command::new(|ctx| {
             let ctx = ctx.lock();

uxi/src/lib.rs

@@ -6,7 +6,7 @@ pub use self::cmd::*;
 pub use self::context::{Bundle, GuardedBundledCtx};
 pub use self::flag::Flag;
 pub use self::inbuilt::BundledCtx;
-pub use self::parameter::{Number, Parameter};
+pub use self::parameter::Parameter;
 
 // Non-namespaced modules.
 mod client;

uxi/src/parameter.rs

@@ -1,8 +1,7 @@
 use std::collections::HashMap;
 use std::fmt;
 
-pub type Number = i32;
-
+/// Parameter is the schema for the Client's options.
 #[derive(Clone)]
 pub enum Parameter {
     /// Check represents a checkbox parameter which can be true or false.
@@ -21,7 +20,7 @@ pub enum Parameter {
     /// value, and the third argument is the maximum value of this parameter. The
     /// minimum and maximum bounds are inclusive and and the default must be in
     /// the range defined by them.
-    Spin(Number, Number, Number),
+    Spin(i64, i64, i64),
 
     /// Combo represents a combo box which can have the value of one of the
     /// predefined strings.
@@ -35,7 +34,7 @@ pub enum Parameter {
 pub struct Values {
     checks: HashMap<String, bool>,
     strings: HashMap<String, String>,
-    numbers: HashMap<String, Number>,
+    numbers: HashMap<String, i64>,
 }
 
 impl Values {
@@ -47,7 +46,7 @@ impl Values {
         self.strings.get(name).cloned()
     }
 
-    pub fn get_spin(&self, name: &str) -> Option<Number> {
+    pub fn get_spin(&self, name: &str) -> Option<i64> {
         self.numbers.get(name).copied()
     }
 }