From 82c02fbdd7cd3eb009049ad0220457baa5be5548 Mon Sep 17 00:00:00 2001 From: Pauline Date: Tue, 30 Jul 2024 10:04:59 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20doc:=20docum=20ent=20atinon?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- packages/core/src/error.rs | 29 +++++++++++++++++++---------- packages/core/src/logger.rs | 6 +++--- packages/core/src/utils/io.rs | 6 ++++++ packages/core/src/utils/mod.rs | 13 ++++++++++++- packages/core/src/utils/platform.rs | 5 ++++- packages/core/src/utils/watcher.rs | 13 +++++-------- 6 files changed, 49 insertions(+), 23 deletions(-) diff --git a/packages/core/src/error.rs b/packages/core/src/error.rs index 46969247..424a9ecd 100644 --- a/packages/core/src/error.rs +++ b/packages/core/src/error.rs @@ -8,15 +8,15 @@ use tracing_error::InstrumentError; #[derive(thiserror::Error, Debug)] pub enum ErrorKind { /// Wrapper around [`tokio::sync::AcquireError`] to handle sempahore errors. - #[error("failed to manage a tokio semaphore: {0}")] + #[error("failed to acquire a tokio semaphore: {0}")] AcquireError(#[from] tokio::sync::AcquireError), /// Wrapper around [`tokio::sync::oneshot::error::RecvError`] to handle recieve errors. - #[error("tokio recieve error: {0}")] + #[error("failed to handle async reciever: {0}")] RecvError(#[from] tokio::sync::oneshot::error::RecvError), /// Wrapper around [`tokio::task::JoinError`] to handle tokio join handle errors. - #[error("tokio join handle error: {0}")] + #[error("failed to handle an async task: {0}")] JoinError(#[from] tokio::task::JoinError), /// Wrapper around [`flate2::CompressError`] to handle flate compression errors. @@ -28,11 +28,11 @@ pub enum ErrorKind { DeflateError(#[from] flate2::DecompressError), /// Wrapper around [`uuid::Error`] to handle UUID parsing errors. - #[error("failed to parse uuids: {0}")] + #[error("failed to parse and handle uuids: {0}")] UUIDError(#[from] uuid::Error), /// Wrapper around [`interpulse::Error`] to handle interpulse errors. - #[error("metadata error: {0}")] + #[error("failed to parse and handle metadata: {0}")] MetadataError(#[from] interpulse::Error), /// Wrapper around [`serde_json::Error`] to handle Serde JSON parsing errors. @@ -44,7 +44,7 @@ pub enum ErrorKind { INIError(#[from] serde_ini::de::Error), /// Wrapper around [`reqwest::Error`] to handle HTTP errors. - #[error("failed to establish a HTTP connection: {0}")] + #[error("failed to establish an http connection: {0}")] HTTPError(#[from] reqwest::Error), /// Wrapper around [`zip::result::ZipError`] to handle zip errors. @@ -60,7 +60,7 @@ pub enum ErrorKind { AnyhowError(#[from] anyhow::Error), /// Wrapper around [`chrono::ParseError`] to handle date parsing errors. - #[error("failed to parse a date: {0}")] + #[error("failed to parse and handle datetime: {0}")] ChronoError(#[from] chrono::ParseError), /// Wrapper around [`crate::state::DirectoryError`] to handle directory errors. @@ -104,11 +104,11 @@ pub enum ErrorKind { IOError(#[from] crate::utils::io::IOError), /// Wrapper around [`std::io::Error`] to handle non-wrapped std::io errors. - #[error("I/O (std) error: {0}")] + #[error("error handling standard IO operations: {0}")] StdIOError(#[from] std::io::Error), /// Wrapper around [`crate::utils::java::JavaError`] to handle java errors. - #[error("there was an error managing java installations: {0}")] + #[error("failed to manage java installations: {0}")] JavaError(#[from] crate::utils::java::JavaError), /// Wrapper around [`crate::store::StrongholdError`] to handle stronghold errors. @@ -117,35 +117,43 @@ pub enum ErrorKind { /// Wrapper around [`tauri::Error`] to handle Tauri errors when the feature flag is enabled #[cfg(feature = "tauri")] - #[error("Tauri error: {0}")] + #[error("error handling tauri: {0}")] TauriError(#[from] tauri::Error), } +/// A safe, accessible error structure wrapper around [`ErrorKind`] for use with [`tracing_error`]. #[derive(Debug)] pub struct Error { + /// The raw, inner [`ErrorKind`], wrapped in an [`Arc`]. pub raw: std::sync::Arc, + /// The traced [`ErrorKind`] ([`tracing_error`]) to be parsed and logged. pub source: tracing_error::TracedError>, } impl From for String { + /// Converts an [`Error`] into a [`String`] value. fn from(value: Error) -> Self { value.to_string() } } impl std::error::Error for Error { + /// Get the source for the inner traced [`Error`]. fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { self.source.source() } } impl std::fmt::Display for Error { + /// Format the [`Error`] and output it into the formatter buffer. fn fmt(&self, fmt: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { write!(fmt, "{}", self.source) } } impl> From for Error { + /// Converts an [`ErrorKind`] error into a traced [`Error`]. + /// Useful for reducing error mapping and standardizing error types. fn from(source: E) -> Self { let error = Into::::into(source); let boxed_error = std::sync::Arc::new(error); @@ -158,6 +166,7 @@ impl> From for Error { } impl ErrorKind { + /// Converts the current [`ErrorKind`] into a traced [`Error`]. pub fn as_error(self) -> Error { self.into() } diff --git a/packages/core/src/logger.rs b/packages/core/src/logger.rs index 1d742da0..e7d3bd88 100644 --- a/packages/core/src/logger.rs +++ b/packages/core/src/logger.rs @@ -4,7 +4,7 @@ //! //! - `RUST_LOG=xxx` is a variable which defines tracing configuration (`ERROR > WARN > INFO > DEBUG > TRACE`) //! - `RUST_LOG="onelauncher=trace"` will show **all** mesages from OneLauncher and not other dependencies. -//! - `RUST_LOG="info"` will show info, warn, and error logs.` +//! - `RUST_LOG="info"` will show info, warn, and error logs. //! //! Errors returned to [`tauri`] are displayed as tracing error logs. //! These errors also include an attached span trace if the error is from a [`tracing_error`] and the level is info, debug, or trace. @@ -15,7 +15,7 @@ use tracing_appender::non_blocking::WorkerGuard; -/// Start the global [`tracing`] logger in development. +/// Initialize the global [`tracing`] logger in development. #[cfg(debug_assertions)] pub fn start_logger() -> Option { use tracing_subscriber::prelude::*; @@ -34,7 +34,7 @@ pub fn start_logger() -> Option { None } -/// Start the global [`tracing`] logger in production. +/// Initialize the global [`tracing`] logger in production. #[cfg(not(debug_assertions))] pub fn start_logger() -> Option { use crate::store::Directories; diff --git a/packages/core/src/utils/io.rs b/packages/core/src/utils/io.rs index e8fd4ae6..3a7ce889 100644 --- a/packages/core/src/utils/io.rs +++ b/packages/core/src/utils/io.rs @@ -9,27 +9,33 @@ use tokio::task::spawn_blocking; /// A wrapper around generic and unhelpful [`std::io::Error`] messages. #[derive(Debug, thiserror::Error)] pub enum IOError { + /// A wrapped [`std::io::Error`] along with the path involved in the error. #[error("{source}, path: {path}")] IOErrorWrapper { #[source] source: std::io::Error, path: String, }, + /// A wrapped [`zip::result::ZipError`]. #[error(transparent)] ZipError(#[from] zip::result::ZipError), + /// A wrapped [`std::io::Error`]. #[error(transparent)] IOError(#[from] std::io::Error), } impl IOError { + /// Converts a [`std::io::Error`] into an [`IOError`]. pub fn from(source: std::io::Error) -> Self { Self::IOError(source) } + /// Converts a [`zip::result::ZipError`] into an [`IOError`]. pub fn from_zip(source: zip::result::ZipError) -> Self { Self::ZipError(source) } + /// Converts a [`std::io::Error`] and the path involved in the error into an [`IOErrror`]. pub fn with_path(source: std::io::Error, path: impl AsRef) -> Self { let path = path.as_ref().to_string_lossy().to_string(); diff --git a/packages/core/src/utils/mod.rs b/packages/core/src/utils/mod.rs index 26a624e0..1b25e81a 100644 --- a/packages/core/src/utils/mod.rs +++ b/packages/core/src/utils/mod.rs @@ -1,10 +1,21 @@ -//! OneLauncher utility functions +//! **OneLauncher Utilities** +//! Standard asynchronous utilities and wrappers for use in the launcher. +//! +//! - [`io`]: Async wrapper around [`tokio::fs`] and [`std::io::Error`] for our error system. +//! - [`http`]: Async extensions and wrappers around [`reqwest`] functions. +//! - [`java`]: Async utilities for managing and downloading Java versions. +//! - [`platform`]: Async utilities for managing OS-specific [`interpulse`] operations and rules. +//! - [`watcher`]: Async utilities for watching files with [`notify`]. + pub mod http; pub mod io; pub mod java; pub mod platform; pub mod watcher; +/// Simple macro that takes a mutable reference and inserts it into a codeblock closure +/// as an owned reference. +/// /// mutable reference gets epically owned by free thinking macro!!!!! (not clickbait) /// im going insane insane insane insane insane insane insane insane insane macro_rules! ref_owned { diff --git a/packages/core/src/utils/platform.rs b/packages/core/src/utils/platform.rs index 2c253ab7..f314c315 100644 --- a/packages/core/src/utils/platform.rs +++ b/packages/core/src/utils/platform.rs @@ -7,6 +7,8 @@ use regex::Regex; // todo: add this to interpulse (maybe, generally we keep it unimplemented but these are pretty basic functions). +/// An extension of [`Os`] for utilities on converting the current system's operating system +/// into an [`Os`] structure for simple management. pub trait OsExt { /// Get the [`Os`] of the current system fn native() -> Self; @@ -52,7 +54,7 @@ impl OsExt for Os { } } -// Platform rule handling +/// Handles an os-specific [`OsRule`], returning if the [`Os`] matches the rule. pub fn os_rule(rule: &OsRule, java_arch: &str, updated: bool) -> bool { let mut rule_match = true; @@ -77,6 +79,7 @@ pub fn os_rule(rule: &OsRule, java_arch: &str, updated: bool) -> bool { rule_match } +/// Gets the seperator between Java classpaths in metadata (`";"` on Windows, `";"` on others). pub fn classpath_separator(java_arch: &str) -> &'static str { match Os::native_arch(java_arch) { Os::Osx | Os::OsxArm64 | Os::Linux | Os::LinuxArm32 | Os::LinuxArm64 | Os::Unknown => ":", diff --git a/packages/core/src/utils/watcher.rs b/packages/core/src/utils/watcher.rs index 0a284596..a7b3014e 100644 --- a/packages/core/src/utils/watcher.rs +++ b/packages/core/src/utils/watcher.rs @@ -1,4 +1,4 @@ -//! **Watcher Utilities* +//! **Watcher Utilities** //! //! Async utilities for watching files with [`notify`]. @@ -11,6 +11,8 @@ use futures::{SinkExt, StreamExt}; use notify::RecommendedWatcher; use notify_debouncer_mini::{new_debouncer, DebounceEventResult, Debouncer}; +/// Creates and initializes an FS watcher for the `clusters` directory, returning +/// the watcher as a [`Debouncer`]. pub async fn initialize_watcher() -> crate::Result> { let (mut sender, mut rscv) = channel(1); let watcher = new_debouncer( @@ -39,13 +41,8 @@ pub async fn initialize_watcher() -> crate::Result for cmp in components.by_ref() { formatted.push(cmp); - if matched { - break; - } - // really simple fs watcher to check in any cluster files have been modified by outside forces - if cmp.as_os_str() == "clusters" { - matched = true; - } + if matched { break; } + if cmp.as_os_str() == "clusters" { matched = true; } } let sub = components.next().is_none();