diff --git a/src/internal/clean.rs b/src/internal/clean.rs index 7ffe82a..5a45d51 100644 --- a/src/internal/clean.rs +++ b/src/internal/clean.rs @@ -2,6 +2,7 @@ use regex::Regex; use crate::{log, Options}; +/// Strips packages from versioning and other extraneous information. pub fn clean(a: &[String], options: Options) -> Vec { // Strip versioning from package names let r = Regex::new(r"(\S+)((?:>=|<=|>|<|=\W)\S+$)").unwrap(); diff --git a/src/internal/detect.rs b/src/internal/detect.rs index 6bf5f40..3ef5137 100644 --- a/src/internal/detect.rs +++ b/src/internal/detect.rs @@ -4,6 +4,7 @@ use crate::internal::error::SilentUnwrap; use crate::internal::exit_code::AppExitCode; use crate::{prompt, spinner, warn}; +/// Searches the filesystem for .pacnew files and helps the user deal with them. pub fn detect() { // Start spinner let sp = spinner!("Scanning for pacnew files"); diff --git a/src/internal/error.rs b/src/internal/error.rs index 3e2c1f8..2a46f24 100644 --- a/src/internal/error.rs +++ b/src/internal/error.rs @@ -20,7 +20,7 @@ impl Display for AppError { match self { Self::Io(io) => Display::fmt(io, f), Self::Other(s) => Display::fmt(s, f), - Self::NonZeroExit => Display::fmt("exited with non zero code", f), + Self::NonZeroExit => Display::fmt("Exited with non-zero exit code", f), } } } @@ -53,7 +53,7 @@ impl SilentUnwrap for AppResult { fn silent_unwrap(self, exit_code: AppExitCode) -> T { match self { Ok(val) => val, - Err(_) => crash!(exit_code, "an error occurred"), + Err(_) => crash!(exit_code, "An error occurred"), } } } diff --git a/src/internal/exit_code.rs b/src/internal/exit_code.rs index f21267a..b3aaa8f 100644 --- a/src/internal/exit_code.rs +++ b/src/internal/exit_code.rs @@ -1,4 +1,5 @@ #[allow(clippy::module_name_repetitions)] +/// Defined exit codes for the program pub enum AppExitCode { RunAsRoot = 1, FailedCreatingPaths = 2, diff --git a/src/internal/initialise.rs b/src/internal/initialise.rs index 5c58549..eaba826 100644 --- a/src/internal/initialise.rs +++ b/src/internal/initialise.rs @@ -3,6 +3,7 @@ use std::path::Path; use crate::{crash, internal::exit_code::AppExitCode, log, Options}; +/// Ensure all required directories and files exist. pub fn init(options: Options) { // Initialise variables let verbosity = options.verbosity; diff --git a/src/internal/rpc.rs b/src/internal/rpc.rs index bf0cb67..81ca890 100644 --- a/src/internal/rpc.rs +++ b/src/internal/rpc.rs @@ -1,6 +1,7 @@ use std::sync::Arc; #[derive(serde::Deserialize, Debug, Clone)] +/// Struct for deserializing RPC results. pub struct Package { #[serde(rename = "Name")] pub name: String, @@ -23,12 +24,14 @@ pub struct Package { } #[derive(serde::Deserialize)] +/// Struct for retreiving search results from the AUR. pub struct SearchResults { pub resultcount: u32, pub results: Vec, } #[derive(Clone)] +/// Struct for retreiving package information from the AUR. pub struct InfoResults { pub found: bool, pub package: Option, @@ -36,6 +39,7 @@ pub struct InfoResults { pub const URL: &str = "https://aur.archlinux.org/"; +/// Return a struct of type [`InfoResults`] from the AUR. pub fn rpcinfo(pkg: &str) -> InfoResults { // Initialise TLS connector let tls_connector = Arc::new(native_tls::TlsConnector::new().unwrap()); @@ -70,6 +74,7 @@ pub fn rpcinfo(pkg: &str) -> InfoResults { } } +/// Return a struct of type [`SearchResults`] from the AUR. pub fn rpcsearch(pkg: &str) -> SearchResults { // Initialise TLS connector let tls_connector = Arc::new(native_tls::TlsConnector::new().unwrap()); diff --git a/src/internal/sort.rs b/src/internal/sort.rs index f32c671..f0f1834 100644 --- a/src/internal/sort.rs +++ b/src/internal/sort.rs @@ -3,6 +3,7 @@ use std::process::{Command, Stdio}; use crate::internal::{clean, rpc, structs}; use crate::{log, Options}; +/// Sorts the given packages into an [`crate::internal::structs::Sorted`] pub fn sort(input: &[String], options: Options) -> structs::Sorted { // Initialise variables let mut repo: Vec = vec![]; diff --git a/src/internal/structs.rs b/src/internal/structs.rs index 48a3edf..62e0764 100644 --- a/src/internal/structs.rs +++ b/src/internal/structs.rs @@ -1,4 +1,5 @@ #[derive(Debug, serde::Serialize)] +/// Struct for packages exiting [`crate::internal::sort()`]. pub struct Sorted { #[allow(dead_code)] pub repo: Vec, @@ -15,6 +16,7 @@ impl Sorted { } #[derive(Clone, Copy)] +/// Options to be passed down to internal functions pub struct Options { pub verbosity: usize, pub noconfirm: bool, diff --git a/src/internal/sudoloop.rs b/src/internal/sudoloop.rs index bcefc31..dd40c2b 100644 --- a/src/internal/sudoloop.rs +++ b/src/internal/sudoloop.rs @@ -3,7 +3,7 @@ use std::time::Duration; use crate::ShellCommand; -/// Loop sudo so it doesn't time out +/// Loop sudo so longer builds don't time out #[allow(clippy::module_name_repetitions)] pub fn start_sudoloop() { prompt_sudo(); diff --git a/src/internal/utils.rs b/src/internal/utils.rs index 1d89ee2..feb0c55 100644 --- a/src/internal/utils.rs +++ b/src/internal/utils.rs @@ -17,6 +17,7 @@ const PROMPT_YN_DEFAULT_TRUE: &str = "[Y/n]"; const PROMPT_YN_DEFAULT_FALSE: &str = "[y/N]"; #[macro_export] +/// Macro for printing a message to stdout. macro_rules! info { ($($arg:tt)+) => { $crate::internal::utils::log_info(format!($($arg)+)) @@ -24,6 +25,7 @@ macro_rules! info { } #[macro_export] +/// Macro for printing a warning message non-destructively. macro_rules! warn { ($($arg:tt)+) => { $crate::internal::utils::log_warn(format!($($arg)+)) @@ -31,6 +33,7 @@ macro_rules! warn { } #[macro_export] +/// Macro for printing a message and destructively exiting macro_rules! crash { ($exit_code:expr, $($arg:tt)+) => { $crate::internal::utils::log_and_crash(format!($($arg)+), $exit_code) @@ -38,6 +41,7 @@ macro_rules! crash { } #[macro_export] +/// Macro for logging to stderr macro_rules! log { ($($arg:tt)+) => { $crate::internal::utils::log_debug(format!($($arg)+)) @@ -45,6 +49,7 @@ macro_rules! log { } #[macro_export] +/// Macro for prompting the user with a yes/no question. macro_rules! prompt { (default $default:expr, $($arg:tt)+) => { $crate::internal::utils::prompt_yn(format!($($arg)+), $default) @@ -52,12 +57,14 @@ macro_rules! prompt { } #[macro_export] +/// Macro for creating a spinner. macro_rules! spinner { ($($arg:tt)+) => { $crate::internal::utils::spinner_fn(format!($($arg)+)) } } +/// Print a formatted message to stdout. pub fn log_info(msg: String) { let msg = if internal::uwu_enabled() { uwu!(&msg) @@ -75,6 +82,7 @@ pub fn log_info(msg: String) { ); } +/// Print a non-destructive warning message pub fn log_warn(msg: String) { let msg = if internal::uwu_enabled() { uwu!(&msg) @@ -92,6 +100,7 @@ pub fn log_warn(msg: String) { ); } +/// Logs a message and exits the program with the given exit code. pub fn log_and_crash(msg: String, exit_code: AppExitCode) -> ! { let msg = if internal::uwu_enabled() { uwu!(&msg) @@ -110,6 +119,7 @@ pub fn log_and_crash(msg: String, exit_code: AppExitCode) -> ! { exit(exit_code as i32); } +/// Logs a message to stderr with timestamp pub fn log_debug(msg: String) { let msg = if internal::uwu_enabled() && internal::uwu_debug_enabled() { uwu!(&msg) @@ -127,6 +137,7 @@ pub fn log_debug(msg: String) { ); } +/// Prompts the user for a yes/no answer. pub fn prompt_yn(question: String, default_true: bool) -> bool { let yn_prompt = if default_true { PROMPT_YN_DEFAULT_TRUE @@ -186,6 +197,7 @@ impl Spinner { } } +/// Returns a spinner that can be used to display progress. pub fn spinner_fn(text: String) -> Spinner { let text = if internal::uwu_enabled() { uwu!(&text) @@ -205,6 +217,7 @@ pub fn spinner_fn(text: String) -> Spinner { } } +/// Opens an [`&String`] in `less`. pub fn pager(text: &String) -> io::Result<()> { let text = if internal::uwu_enabled() { uwu!(text) diff --git a/src/operations/aur_install.rs b/src/operations/aur_install.rs index a1a94b7..074653d 100644 --- a/src/operations/aur_install.rs +++ b/src/operations/aur_install.rs @@ -15,6 +15,7 @@ use crate::{crash, info, log, prompt, warn, Options}; const AUR_CACHE: &str = ".cache/ame"; +/// Return a list of all files/dirs in a directory. fn list(dir: &str) -> Vec { let dirs = fs::read_dir(Path::new(&dir)).unwrap(); let dirs: Vec = dirs @@ -34,6 +35,7 @@ fn list(dir: &str) -> Vec { dirs } +/// Returns and creates a temporary directory for amethyst to use fn mktemp() -> String { let tempdir = Command::new("mktemp") .args(&["-d", "/tmp/ame.XXXXXX.tmp"]) @@ -44,6 +46,7 @@ fn mktemp() -> String { String::from_utf8(tempdir).unwrap().trim().to_string() } +/// Help the user review and/or edit an AUR package before installing fn review(cachedir: &str, pkg: &str, orig_cachedir: &str) { // Prompt user to view PKGBUILD let p0 = prompt!(default false, "Would you like to review and/or edit {}'s PKGBUILD (and any adjacent build files if present)?", pkg); @@ -114,6 +117,7 @@ fn review(cachedir: &str, pkg: &str, orig_cachedir: &str) { }; } +/// Finalize a build/install process fn finish(cachedir: &str, pkg: &str, options: &Options) { // Install all packages from cachedir except `pkg` using --asdeps let dirs = list(cachedir); @@ -171,6 +175,7 @@ fn finish(cachedir: &str, pkg: &str, options: &Options) { } } +/// Clone a package from the AUR fn clone(pkg: &String, pkgcache: &str, options: &Options) { let url = crate::internal::rpc::URL; @@ -225,6 +230,7 @@ fn clone(pkg: &String, pkgcache: &str, options: &Options) { } } +/// General function to handle installing AUR packages. pub fn aur_install(a: Vec, options: Options, orig_cachedir: &str) { // Initialise variables let cachedir = if options.asdeps || !orig_cachedir.is_empty() { diff --git a/src/operations/clean.rs b/src/operations/clean.rs index 7d47203..982d5bd 100644 --- a/src/operations/clean.rs +++ b/src/operations/clean.rs @@ -9,6 +9,7 @@ use crate::log; use crate::prompt; use crate::Options; +/// Help the user in clearing orphaned packages and pacman cache. pub fn clean(options: Options) { let verbosity = options.verbosity; let noconfirm = options.noconfirm; @@ -69,14 +70,27 @@ pub fn clean(options: Options) { } } + // Prompt the user whether to clear the Amethyst cache + let clear_ame_cache = prompt!(default false, "Clear Amethyst's internal PKGBUILD cache?"); + if clear_ame_cache { + // Remove ~/.cache/ame + Command::new("rm") + .arg("-rf") + .arg("~/.cache/ame") + .spawn() + .unwrap() + .wait() + .unwrap(); + } + // Prompt the user whether to clear cache or not - let clear_cache = if noconfirm { + let clear_pacman_cache = if noconfirm { true } else { prompt!(default false, "Also clear pacman's package cache?") }; - if clear_cache { + if clear_pacman_cache { // Build pacman args let mut pacman_args = vec!["-Sc"]; if noconfirm { diff --git a/src/operations/install.rs b/src/operations/install.rs index c2fb2a0..2873e33 100644 --- a/src/operations/install.rs +++ b/src/operations/install.rs @@ -3,6 +3,7 @@ use crate::internal::error::SilentUnwrap; use crate::internal::exit_code::AppExitCode; use crate::{crash, info, log, Options}; +/// Help the user install a package from the pacman repos pub fn install(packages: &[String], options: Options) { info!("Installing packages {} from repos", &packages.join(", ")); diff --git a/src/operations/search.rs b/src/operations/search.rs index 6117649..f888a08 100644 --- a/src/operations/search.rs +++ b/src/operations/search.rs @@ -9,6 +9,7 @@ use crate::internal::rpc::rpcsearch; use crate::{log, Options}; #[allow(clippy::module_name_repetitions)] +/// Searches for packages from the AUR and returns wrapped results pub fn aur_search(query: &str, options: Options) -> String { // Query AUR for package info let res = rpcsearch(query); @@ -71,6 +72,7 @@ struct SearchResult { } #[allow(clippy::module_name_repetitions)] +/// Searches for packages from the repos and returns wrapped results pub fn repo_search(query: &str, options: Options) -> String { // Initialise variables let verbosity = options.verbosity; diff --git a/src/operations/uninstall.rs b/src/operations/uninstall.rs index d0e5e07..7abe2bd 100644 --- a/src/operations/uninstall.rs +++ b/src/operations/uninstall.rs @@ -3,6 +3,7 @@ use crate::internal::error::SilentUnwrap; use crate::internal::exit_code::AppExitCode; use crate::{log, Options}; +/// Helps the user in uninstalling installed packages. pub fn uninstall(packages: &[String], options: Options) { // Build pacman args let mut pacman_args = vec!["-Rs"]; diff --git a/src/operations/upgrade.rs b/src/operations/upgrade.rs index f413371..8b05d5c 100644 --- a/src/operations/upgrade.rs +++ b/src/operations/upgrade.rs @@ -13,6 +13,7 @@ struct QueriedPackage { pub version: String, } +/// Helps the user upgrade installed packages, repo and AUR. pub fn upgrade(options: Options, args: UpgradeArgs, cachedir: &str) { // Initialise variables let verbosity = options.verbosity;