docstrings

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<String> {
     // Strip versioning from package names
     let r = Regex::new(r"(\S+)((?:>=|<=|>|<|=\W)\S+$)").unwrap();

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");

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<T> SilentUnwrap<T> for AppResult<T> {
     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"),
         }
     }
 }

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,

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;

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<Package>,
 }
 
 #[derive(Clone)]
+/// Struct for retreiving package information from the AUR.
 pub struct InfoResults {
     pub found: bool,
     pub package: Option<Package>,
@@ -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());

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<String> = vec![];

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<String>,
@@ -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,

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();

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)

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<String> {
     let dirs = fs::read_dir(Path::new(&dir)).unwrap();
     let dirs: Vec<String> = dirs
@@ -34,6 +35,7 @@ fn list(dir: &str) -> Vec<String> {
     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<String>, options: Options, orig_cachedir: &str) {
     // Initialise variables
     let cachedir = if options.asdeps || !orig_cachedir.is_empty() {

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 {

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(", "));
 

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;

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"];

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;