runner: Add documentation

Author: cyberphantom52

src/runner/gptk.rs

@@ -5,7 +5,15 @@ use std::path::{Path, PathBuf};
 ///
 /// GPTK is Apple's translation layer that allows running Windows games on macOS,
 /// particularly on Apple Silicon Macs. It combines Wine with Apple's D3DMetal
-/// to support DirectX 11 and 12 games.
+/// to support DirectX 11 and 12 games with hardware acceleration.
+///
+/// # Features
+///
+/// - DirectX 11 and 12 support through D3DMetal translation
+/// - Optimized for Apple Silicon architecture
+/// - Integration with macOS graphics stack
+/// - Metal Performance Shaders acceleration
+/// - Enhanced gaming compatibility on macOS
 ///
 /// # Requirements
 /// - macOS 14 Sonoma or later

src/runner/mod.rs

@@ -16,17 +16,39 @@ use std::{
     process::Command,
 };
 
-/// Common information about a runner
+/// Contains metadata and paths for any runner implementation. This struct is used
+/// internally by all runner types to store their basic information.
 #[derive(Debug)]
 pub struct RunnerInfo {
+    /// Human-readable name of the runner, typically derived from the directory name
     name: String,
+    /// Version string obtained from the runner's `--version` output
     version: String,
+    /// Base directory where the runner is installed
     directory: PathBuf,
+    /// Relative path to the main executable within the directory
     executable: PathBuf,
 }
 
 impl RunnerInfo {
-    // This fuction is only meant to be called by the runners themselves hence this is not public
+    /// Create a new RunnerInfo by validating the directory and executable
+    ///
+    /// This function is only meant to be called by the runners themselves, hence it's not public.
+    /// It performs validation to ensure the directory exists and contains the specified executable.
+    ///
+    /// # Arguments
+    ///
+    /// * `directory` - The base directory where the runner is installed
+    /// * `executable` - The relative path to the executable within the directory
+    ///
+    /// # Returns
+    ///
+    /// Returns a `RunnerInfo` instance if validation succeeds
+    ///
+    /// # Errors
+    ///
+    /// This function will return an error if the directory or executable path is invalid,
+    /// or if the executable cannot be executed to determine its version.
     fn try_from(directory: &Path, executable: &Path) -> Result<Self, Error> {
         if !directory.exists() {
             return Err(std::io::Error::new(
@@ -77,41 +99,110 @@ impl RunnerInfo {
     }
 
     /// Get the full path to the executable for the runner
+    ///
+    /// Combines the base directory with the relative executable path to provide
+    /// the complete path that can be used to execute the runner.
+    ///
+    /// # Returns
+    ///
+    /// A `PathBuf` containing the full path to the runner's executable
     pub fn executable_path(&self) -> PathBuf {
         self.directory.join(&self.executable)
     }
 }
 
 impl RunnerInfo {
-    /// Name of the runner
+    /// Get the name of the runner
+    ///
+    /// Returns the human-readable name, typically derived from the directory name
+    /// where the runner is installed.
+    ///
+    /// # Returns
+    ///
+    /// A string slice containing the runner's name
     pub fn name(&self) -> &str {
         &self.name
     }
 
-    /// Version of the runner
+    /// Get the version of the runner
+    ///
+    /// Returns the version string as reported by the runner's `--version` command.
+    /// If the version cannot be determined, this may return the runner's name instead.
+    ///
+    /// # Returns
+    ///
+    /// A string slice containing the runner's version information
     pub fn version(&self) -> &str {
         &self.version
     }
 
-    /// Directory where the runner is located
+    /// Returns the directory path where the runner is installed.
+    ///
+    /// # Returns
+    ///
+    /// A path reference to the runner's installation directory
     pub fn directory(&self) -> &Path {
         &self.directory
     }
 }
 
+/// Trait defining the common interface for all Windows compatibility runners
+///
+/// All runners in this module implement this trait, providing a unified way to interact
+/// with different compatibility layers like Wine, Proton, UMU, and GPTK.
 pub trait Runner {
     /// Get the Wine runner associated with this runner
     ///
-    /// This is possible because all runners are built on top of Wine
+    /// All runners are built on top of Wine, so this method provides access to the
+    /// underlying Wine instance. This allows for Wine-specific operations and
+    /// configuration even when using higher-level runners like Proton.
+    ///
+    /// # Returns
+    ///
+    /// A reference to the underlying Wine runner instance
     fn wine(&self) -> &Wine;
 
-    /// Get the common runner information
+    /// Provides access to metadata about the runner including its name, version,
+    /// installation directory, and executable path.
+    ///
+    /// # Returns
+    ///
+    /// A reference to the runner's information structure
     fn info(&self) -> &RunnerInfo;
 
-    /// Get the common runner information
+    /// Get a mutable reference to the common runner information
+    ///
+    /// Allows modification of the runner's metadata. This is typically used
+    /// internally by runner implementations during initialization.
+    ///
+    /// # Returns
+    ///
+    /// A mutable reference to the runner's information structure
     fn info_mut(&mut self) -> &mut RunnerInfo;
 
-    /// Check if the runner executable is available and functional
+    /// Performs basic validation to ensure the runner can be executed. The default
+    /// implementation checks if the executable file exists and is accessible.
+    /// Individual runners may override this to perform additional checks.
+    ///
+    /// # Returns
+    ///
+    /// `true` if the runner appears to be functional, `false` otherwise
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use bottles_core::runner::{Wine, Runner};
+    /// use std::path::Path;
+    ///
+    /// let wine_path = Path::new("/usr/bin/wine");
+    /// if let Ok(wine) = Wine::try_from(wine_path) {
+    ///     if wine.is_available() {
+    ///         println!("Wine is ready to use");
+    ///     } else {
+    ///         println!("Wine is not available");
+    ///     }
+    /// }
+    /// ```
     fn is_available(&self) -> bool {
         let executable_path = self.info().executable_path();
         executable_path.exists() && executable_path.is_file()

src/runner/proton.rs

@@ -1,9 +1,16 @@
 use super::{Runner, RunnerInfo, Wine};
 use std::path::{Path, PathBuf};
 
-// TODO: These need to be set to use proton outside steam
-// STEAM_COMPAT_DATA_PATH
-// STEAM_COMPAT_CLIENT_INSTALL_PATH
+/// Proton runner implementation
+///
+/// Proton is Valve's Wine fork designed specifically for gaming on Linux. It includes
+/// numerous patches and enhancements over standard Wine, making it particularly
+/// effective for running Windows games through Steam or standalone.
+///
+/// # Note
+/// When used outside of Steam, Proton requires specific environment variables:
+/// - `STEAM_COMPAT_DATA_PATH`: Path to store compatibility data
+/// - `STEAM_COMPAT_CLIENT_INSTALL_PATH`: Steam installation directory
 #[derive(Debug)]
 pub struct Proton {
     info: RunnerInfo,

src/runner/umu.rs

@@ -1,9 +1,19 @@
 use super::{Proton, Runner, RunnerInfo, Wine};
 use std::path::{Path, PathBuf};
 
+/// UMU (Unified Launcher) runner implementation
+///
+/// UMU is a universal compatibility layer that wraps other runners like Proton
+/// to provide enhanced game compatibility and launcher functionality. It can
+/// automatically configure optimal settings for different games and provides
+/// a unified interface for various Windows compatibility tools.
 #[derive(Debug)]
 pub struct UMU {
     info: RunnerInfo,
+    /// Underlying Proton runner that UMU wraps
+    ///
+    /// When present, UMU will use this Proton instance to run applications.
+    /// If None, UMU will download the latest Proton version it can find and set that up.
     proton: Option<Proton>,
 }
 

src/runner/wine.rs

@@ -1,16 +1,35 @@
 use super::{Runner, RunnerInfo};
 use std::path::{Path, PathBuf};
 
+/// Wine runner implementation
+///
+/// Wine is the base compatibility layer that all other runners build upon. It provides
+/// the core Windows API translation functionality that allows Windows applications
+/// to run on Unix-like systems.
 #[derive(Debug)]
 pub struct Wine {
     info: RunnerInfo,
 }
 
+/// Architecture for Wine prefix creation
+///
+/// Determines whether a Wine prefix should be configured for 32-bit or 64-bit
+/// Windows compatibility. This affects which Windows applications can run
+/// in the prefix
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum PrefixArch {
+    /// 32-bit Windows prefix architecture
     Win32,
+    /// 64-bit Windows prefix architecture (recommended)
     Win64,
 }
 
+/// Windows version compatibility settings
+///
+/// Specifies which version of Windows the Wine prefix should emulate.
+/// Different applications may require specific Windows versions for
+/// optimal compatibility.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum WindowsVersion {
     Win7,
     Win8,