📝 doc: docum ent atinon

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<ErrorKind>,
+	/// The traced [`ErrorKind`] ([`tracing_error`]) to be parsed and logged.
 	pub source: tracing_error::TracedError<std::sync::Arc<ErrorKind>>,
 }
 
 impl From<Error> 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<E: Into<ErrorKind>> From<E> 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::<ErrorKind>::into(source);
 		let boxed_error = std::sync::Arc::new(error);
@@ -158,6 +166,7 @@ impl<E: Into<ErrorKind>> From<E> for Error {
 }
 
 impl ErrorKind {
+	/// Converts the current [`ErrorKind`] into a traced [`Error`].
 	pub fn as_error(self) -> Error {
 		self.into()
 	}

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<WorkerGuard> {
 	use tracing_subscriber::prelude::*;
@@ -34,7 +34,7 @@ pub fn start_logger() -> Option<WorkerGuard> {
 	None
 }
 
-/// Start the global [`tracing`] logger in production.
+/// Initialize the global [`tracing`] logger in production.
 #[cfg(not(debug_assertions))]
 pub fn start_logger() -> Option<WorkerGuard> {
 	use crate::store::Directories;

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<std::path::Path>) -> Self {
 		let path = path.as_ref().to_string_lossy().to_string();
 

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 {

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 => ":",

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<RecommendedWatcher>`].
 pub async fn initialize_watcher() -> crate::Result<Debouncer<RecommendedWatcher>> {
 	let (mut sender, mut rscv) = channel(1);
 	let watcher = new_debouncer(
@@ -39,13 +41,8 @@ pub async fn initialize_watcher() -> crate::Result<Debouncer<RecommendedWatcher>
 
 						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();