From 0cb56ba02411a1c26c3139c385ed034cad20bdc7 Mon Sep 17 00:00:00 2001 From: r0r-5chach Date: Wed, 24 Jul 2024 16:11:35 +0100 Subject: [PATCH] docs --- src/lib.rs | 10 +++++++--- src/main.rs | 1 + src/utils.rs | 11 +++++++---- src/utils/color.rs | 22 +++++++++++++++++----- src/utils/volume.rs | 28 +++++++++++++++------------- src/utils/workspace.rs | 16 +++++++++------- 6 files changed, 56 insertions(+), 32 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 09d6825..26243dc 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,8 +1,9 @@ +//! TODO: Module level docs for lib. use clap::Parser; use utils::{color::color_picker, Util, volume, workspace}; - +/// Contains the utilities the program uses. pub mod utils; - +/// Defines the entrpoint for the main binary implementation of this program. pub fn run() { let args = Args::parse(); @@ -12,7 +13,10 @@ pub fn run() { Util::Workspaces(command) => workspace::parse_command(command), }; } - +/// Stores the arguments passed to the program for the terminal. +/// +/// # Fields +/// - `util`: The utility selected followed by any arguments for the subcommand #[derive(Parser)] #[command( name = "yucky-utils", diff --git a/src/main.rs b/src/main.rs index e7ad5d1..e14a79a 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,3 +1,4 @@ +/// The entrypoint for the program. fn main() { yucky_utils::run(); } //TODO: Handle unwraps diff --git a/src/utils.rs b/src/utils.rs index a1e7ad7..63532b8 100644 --- a/src/utils.rs +++ b/src/utils.rs @@ -1,9 +1,12 @@ +//! Contains the shared logic for the utilities. use clap::{Subcommand, ValueEnum}; - +/// Logic for the Color Picking Utility. pub mod color; +/// Logic for the Volume Management Utility. pub mod volume; +/// Logic for the Workspace Management Utitlity. pub mod workspace; - +/// Invoke the `eww update` command to change the value of an eww variable. pub fn update_eww_var(key: &str, value: &str) { use std::process::Command; @@ -12,14 +15,14 @@ pub fn update_eww_var(key: &str, value: &str) { .arg(format!("{}={}", key, value)) .spawn(); } - +/// Defines the direction a value can be changed in. #[derive(Clone, ValueEnum)] pub enum Direction { Up, Down, Absolute, } - +/// Defines the subcommands for accessing the utilities. #[derive(Subcommand)] pub enum Util { /// Color Picking Utility diff --git a/src/utils/color.rs b/src/utils/color.rs index 9694649..94fa1a8 100644 --- a/src/utils/color.rs +++ b/src/utils/color.rs @@ -1,5 +1,6 @@ +//! TODO: Module Level docs for Color use std::process::Command; - +/// Starts a Hyprpicker instance and parses the result. pub fn color_picker() { use super::update_eww_var; @@ -15,13 +16,24 @@ pub fn color_picker() { std::process::exit(0); } - +/// Defines an RGB color value +/// +/// # Fields +/// - `r`: The red value (0-255) +/// - 'g': The green value (0-255) +/// - 'b': The blue value (0-255) struct Rgb { r: u8, g: u8, b: u8, } impl Rgb { + /// Create a new instance of [Rgb] from a base16 string. + /// + /// # Examples + /// ``` + /// //TODO: Example for Rgb::from_color_hex() + /// ``` fn from_color_hex(color_hex: &str) -> Self { Self { r: hex::decode(color_hex.get(1..3).unwrap_or_else(|| "00")).unwrap()[0], @@ -29,7 +41,7 @@ impl Rgb { b: hex::decode(color_hex.get(5..7).unwrap_or_else(|| "00")).unwrap()[0], } } - + /// Get the 2's compliment of the color. fn get_compliment(&self) -> Self { Self { r: 255 - self.r, @@ -37,12 +49,12 @@ impl Rgb { b: 255 - self.b, } } - + /// Convert the [Rgb] value to a string representation compatible with eww: `rgb(r,g,b)`. fn to_string(&self) -> String { format!("'rgb({}, {}, {})'", self.r, self.g, self.b) } } - +/// Copy the specified [str] (string) to the wayland clipboard. fn add_to_clipboard(string: &str) { let _ = Command::new("wl-copy") .arg(string) diff --git a/src/utils/volume.rs b/src/utils/volume.rs index ecf5928..46b08c8 100644 --- a/src/utils/volume.rs +++ b/src/utils/volume.rs @@ -1,11 +1,10 @@ +//! TODO: Module level docs Volume +use clap::Subcommand; use core::fmt; use std::fmt::{Display, Result}; - -use clap::Subcommand; use super::Direction; - +/// Defines the subcommands that can be used with the volume utility. #[derive(Subcommand)] -#[command(about = "", long_about = None)] //Volume command usage pub enum Command { /// Adjust volume Up/Down by 5% Step { @@ -24,7 +23,7 @@ pub enum Command { /// Get the current volume percent CurrentValue, } - +/// Parses a command and passes it's arguments (if applicable) to the relevant method. pub fn parse_command(command: Command) { match command { Command::CurrentValue => println!("{}", get_current_value()), @@ -33,11 +32,12 @@ pub fn parse_command(command: Command) { Command::ToggleMute { volume } => toggle_mute(volume), } } - +/// Increment or Deincrement the system volume by 5% fn step(directon: Direction) { //onscroll set(5, directon); } - +/// Takes [u8] (saved_volume) and replaces the current volume with the value. +/// The current volume is stored within the `mute_save` eww variable. fn toggle_mute(saved_volume: u8) { //onclick use super::update_eww_var; @@ -47,7 +47,7 @@ fn toggle_mute(saved_volume: u8) { //onclick std::process::exit(0); } - +/// Returns the current [Level] corresponding to the current volume value. fn get_current_icon() -> Level { //for path var in image (add to defpoll) match get_current_value() { value if value <= 0 => Level::Mute, @@ -56,7 +56,7 @@ fn get_current_icon() -> Level { //for path var in image (add to defpoll) _ => Level::High, } } - +/// Returns the current volume value fn get_current_value() -> u8 { //for value in circular-progrss (add to defpoll) use std::process::Command; @@ -70,9 +70,9 @@ fn get_current_value() -> u8 { //for value in circular-progrss (add to defpoll) value.parse().unwrap() } - - - +/// Sets the current volume to [u8] (value) with respect to the [Direction]. +/// If direction = Up | Down : the volume steps by the value. +/// If direction = Absolute : the volume is set to the value%. fn set(value: u8, directon: Direction) { use std::process::Command; @@ -89,7 +89,8 @@ fn set(value: u8, directon: Direction) { .arg("sset").arg("Master").arg(value).arg("> /dev/null") .spawn(); } - +/// Defines the levels the volume can be. +/// These levels correspond to the icons that can be displayed. enum Level { High, Mid, @@ -97,6 +98,7 @@ enum Level { Mute, } impl Display for Level { + /// Formats [Level] to a lowercase string. fn fmt(&self, formatter: &mut fmt::Formatter) -> Result { match self { Level::Mute => write!(formatter, "mute"), diff --git a/src/utils/workspace.rs b/src/utils/workspace.rs index ad2b5e6..6a7c6a8 100644 --- a/src/utils/workspace.rs +++ b/src/utils/workspace.rs @@ -1,8 +1,8 @@ +//! TODO: Module level docs for Workspace use clap::Subcommand; use super::Direction; - +/// Defines the subcommands that can be used with the workspace utility. #[derive(Subcommand)] -#[command(about = "", long_about = "")] pub enum Command { /// Move Up/Down 1 workspace Step { @@ -15,7 +15,7 @@ pub enum Command { /// Get id of the active workspace GetActive, } - +/// Parses a command and passes it's arguments (if applicable) to the relevant method. pub fn parse_command(command: Command) { match command { Command::Empty => empty(), @@ -23,15 +23,15 @@ pub fn parse_command(command: Command) { Command::Step { direction } => step(direction), } } - +/// Increment or Deincrement the active workspace id by 1 fn step(direction: Direction) { set(1, direction); } - +/// Move to the first empty workspace fn empty() { set(0, Direction::Absolute); } - +/// Returns the id of the active workspace fn get_active() -> u8 { use std::process::Command; @@ -45,7 +45,9 @@ fn get_active() -> u8 { value[0].parse().unwrap() } - +/// Sets the active workspace to [u8] (id) with respect to the [Direction]. +/// If direction = Up | Down : the workspace steps by the id. +/// If direction = Absolute: the active workspace is set to the id. fn set(id: u8, direction: Direction) { use std::process::Command;