treewide: add rustdoc to platform-specific modules

Author: NotAShelf

src/darwin.rs

@@ -9,10 +9,18 @@ use crate::util::get_hostname;
 use crate::util::platform;
 use crate::Result;
 
+/// System profile path for darwin configurations
 const SYSTEM_PROFILE: &str = "/nix/var/nix/profiles/system";
+/// Current system profile path for darwin
 const CURRENT_PROFILE: &str = "/run/current-system";
 
 impl DarwinArgs {
+    /// Entry point for processing darwin commands
+    ///
+    /// Handles the different subcommands for darwin configurations:
+    /// - Switch: Builds and activates the configuration
+    /// - Build: Only builds the configuration
+    /// - Repl: Opens a REPL for exploring the configuration
     pub fn run(self) -> Result<()> {
         use DarwinRebuildVariant::{Build, Switch};
         match self.subcommand {
@@ -28,12 +36,25 @@ impl DarwinArgs {
     }
 }
 
+/// Variants of the darwin rebuild operation
+///
+/// Each variant represents a different mode of operation:
+/// - Switch: Build and activate the configuration
+/// - Build: Only build the configuration without activation
 enum DarwinRebuildVariant {
     Switch,
     Build,
 }
 
 impl DarwinRebuildArgs {
+    /// Performs the rebuild operation for darwin configurations
+    ///
+    /// This function handles building and potentially activating darwin configurations.
+    /// It first builds the configuration, then shows a diff of changes compared to the
+    /// current system, and finally activates the configuration if needed.
+    ///
+    /// The darwin activation process is unique and requires special handling compared
+    /// to `NixOS`, particularly around determining whether root privileges are needed.
     fn rebuild(self, variant: DarwinRebuildVariant) -> Result<()> {
         use DarwinRebuildVariant::{Build, Switch};
 
@@ -117,6 +138,10 @@ impl DarwinRebuildArgs {
 }
 
 impl DarwinReplArgs {
+    /// Opens a Nix REPL for exploring darwin configurations
+    ///
+    /// Provides an interactive environment to explore and evaluate
+    /// components of a darwin configuration.
     fn run(self) -> Result<()> {
         if let Installable::Store { .. } = self.installable {
             bail!("Nix doesn't support nix store installables.");

src/home.rs

@@ -10,6 +10,12 @@ use crate::update::update;
 use crate::util::platform;
 
 impl interface::HomeArgs {
+    /// Entry point for processing home-manager commands
+    ///
+    /// Handles the different subcommands for home-manager configurations:
+    /// - Switch: Builds and activates the configuration
+    /// - Build: Only builds the configuration
+    /// - Repl: Opens a REPL for exploring the configuration
     pub fn run(self) -> Result<()> {
         use HomeRebuildVariant::{Build, Switch};
         match self.subcommand {
@@ -25,13 +31,30 @@ impl interface::HomeArgs {
     }
 }
 
+/// Variants of the home-manager rebuild operation
+///
+/// Represents different actions that can be taken with a home-manager configuration:
+/// - Build: Only build the configuration without activating it
+/// - Switch: Build and activate the configuration
 #[derive(Debug)]
 enum HomeRebuildVariant {
     Build,
     Switch,
 }
 
 impl HomeRebuildArgs {
+    /// Performs the rebuild operation for home-manager configurations
+    ///
+    /// This function handles building and potentially activating home-manager configurations.
+    /// The workflow:
+    /// 1. Updates the flake if requested
+    /// 2. Creates a temporary output path
+    /// 3. Builds the configuration with proper specialisation handling
+    /// 4. Compares with the previous generation if it exists
+    /// 5. Activates the configuration if needed
+    ///
+    /// Home Manager has its own specialisation mechanism which this function handles
+    /// by looking in ~/.local/share/home-manager/specialisation.
     fn rebuild(self, variant: HomeRebuildVariant) -> Result<()> {
         use HomeRebuildVariant::Build;
 
@@ -138,6 +161,11 @@ impl HomeRebuildArgs {
 }
 
 impl HomeReplArgs {
+    /// Opens a Nix REPL for exploring home-manager configurations
+    ///
+    /// Provides an interactive environment to explore and evaluate
+    /// components of a home-manager configuration. This is useful for
+    /// debugging or exploring available options.
     fn run(self) -> Result<()> {
         // Use NH_HOME_FLAKE if available, otherwise use the provided installable
         let installable = platform::resolve_env_installable("NH_HOME_FLAKE", self.installable);

src/nixos.rs

@@ -15,12 +15,25 @@ use crate::util::ensure_ssh_key_login;
 use crate::util::get_hostname;
 use crate::util::platform;
 
+/// Path to the system profile on `NixOS`
 const SYSTEM_PROFILE: &str = "/nix/var/nix/profiles/system";
+/// Path to the current system profile on `NixOS`
 const CURRENT_PROFILE: &str = "/run/current-system";
-
+/// Path where `NixOS` stores specialisation information
 const SPEC_LOCATION: &str = "/etc/specialisation";
 
 impl interface::OsArgs {
+    /// Entry point for processing `NixOS` commands
+    ///
+    /// Handles the various subcommands for `NixOS` configurations:
+    /// - Switch: Builds, activates, and makes the configuration the boot default
+    /// - Boot: Builds and makes the configuration the boot default
+    /// - Test: Builds and activates the configuration
+    /// - Build: Only builds the configuration
+    /// - Repl: Opens a REPL for exploring the configuration
+    /// - Info: Lists available generations
+    /// - Rollback: Reverts to a previous generation
+    /// - `BuildVm`: Builds a `NixOS` VM image
     pub fn run(self) -> Result<()> {
         use OsRebuildVariant::{Boot, Build, Switch, Test};
         // Always resolve installable from env var at the top
@@ -67,6 +80,15 @@ impl interface::OsArgs {
     }
 }
 
+/// Variants of the `NixOS` rebuild operation
+///
+/// Each variant represents a different mode of operation with distinct
+/// activation behaviors:
+/// - Build: Only build the configuration
+/// - Switch: Build, activate, and make it the boot default
+/// - Boot: Build and make it the boot default
+/// - Test: Build and activate
+/// - `BuildVm`: Build a VM image for testing
 #[derive(Debug)]
 enum OsRebuildVariant {
     Build,
@@ -77,7 +99,25 @@ enum OsRebuildVariant {
 }
 
 impl OsRebuildArgs {
-    // Accept the resolved installable as a parameter
+    /// Rebuilds a `NixOS` configuration with the given variant and installable
+    ///
+    /// This is the core function for building and deploying `NixOS` configurations.
+    /// It handles:
+    /// 1. SSH key login for remote operations
+    /// 2. Root privilege management
+    /// 3. Flake updates if requested
+    /// 4. Hostname resolution and validation
+    /// 5. Building the configuration
+    /// 6. Specialisation handling
+    /// 7. Remote deployment if `target_host` is specified
+    /// 8. Configuration activation based on variant
+    ///
+    /// The different variants determine which aspects of deployment are executed:
+    /// - Build: Only build the configuration
+    /// - Switch: Build, activate, and make boot default
+    /// - Boot: Build and make boot default
+    /// - Test: Build and activate
+    /// - `BuildVm`: Build a VM image
     fn rebuild_with_installable(
         self,
         variant: OsRebuildVariant,
@@ -196,6 +236,16 @@ impl OsRebuildArgs {
 }
 
 impl OsRollbackArgs {
+    /// Rolls back the system to a previous generation
+    ///
+    /// This function:
+    /// 1. Finds the generation to roll back to (previous or specified)
+    /// 2. Shows a diff between current and target generations
+    /// 3. Sets the system profile to point to the target generation
+    /// 4. Activates the configuration
+    /// 5. Handles failures by rolling back the profile symlink if activation fails
+    ///
+    /// Generation specialisations are properly handled during rollback.
     fn rollback(&self) -> Result<()> {
         // Check if we need root permissions
         let elevate = platform::check_not_root(self.bypass_root_check)?;
@@ -311,6 +361,15 @@ impl OsRollbackArgs {
     }
 }
 
+/// Finds the previous generation in the system profile
+///
+/// This function:
+/// 1. Searches for available system generations
+/// 2. Identifies which one is currently active
+/// 3. Returns the generation immediately before the current one
+///
+/// Returns an error if there are no generations or if the current
+/// generation is already the oldest one.
 fn find_previous_generation() -> Result<generations::GenerationInfo> {
     let profile_path = PathBuf::from(SYSTEM_PROFILE);
 
@@ -357,6 +416,10 @@ fn find_previous_generation() -> Result<generations::GenerationInfo> {
     Ok(generations[current_idx - 1].clone())
 }
 
+/// Finds a specific generation by its number
+///
+/// Searches the system profiles directory for a generation with the
+/// specified number and returns its information if found.
 fn find_generation_by_number(number: u64) -> Result<generations::GenerationInfo> {
     let profile_path = PathBuf::from(SYSTEM_PROFILE);
 
@@ -388,6 +451,10 @@ fn find_generation_by_number(number: u64) -> Result<generations::GenerationInfo>
     Ok(generations[0].clone())
 }
 
+/// Gets the number of the currently active generation
+///
+/// This is useful for rollback operations, especially when needing
+/// to restore the system if activation of an older generation fails.
 fn get_current_generation_number() -> Result<u64> {
     let profile_path = PathBuf::from(SYSTEM_PROFILE);
 
@@ -414,6 +481,13 @@ fn get_current_generation_number() -> Result<u64> {
         .map_err(|_| eyre!("Invalid generation number"))
 }
 
+/// Determines the final attribute name for VM builds
+///
+/// Returns the appropriate Nix attribute based on whether
+/// the VM should include a bootloader:
+/// - "vmWithBootLoader" for VM with bootloader
+/// - "vm" for standard VM
+/// - "toplevel" for regular builds
 pub fn get_final_attr(build_vm: bool, with_bootloader: bool) -> String {
     let attr = if build_vm && with_bootloader {
         "vmWithBootLoader"
@@ -426,6 +500,11 @@ pub fn get_final_attr(build_vm: bool, with_bootloader: bool) -> String {
 }
 
 impl OsReplArgs {
+    /// Opens a Nix REPL for exploring `NixOS` configurations
+    ///
+    /// Provides an interactive environment to explore and evaluate
+    /// components of a `NixOS` configuration. This is useful for
+    /// debugging or exploring available options.
     fn run_with_installable(self, installable: Installable) -> Result<()> {
         // Get hostname, with fallback to system hostname
         let hostname = match self.hostname {
@@ -454,6 +533,13 @@ impl OsReplArgs {
 }
 
 impl OsGenerationsArgs {
+    /// Lists information about available `NixOS` generations
+    ///
+    /// This function:
+    /// 1. Identifies the profile and confirms it exists
+    /// 2. Finds all generations associated with that profile
+    /// 3. Collects metadata about each generation (number, date, etc.)
+    /// 4. Displays the information in a formatted list
     fn info(&self) -> Result<()> {
         let profile = match self.profile {
             Some(ref p) => PathBuf::from(p),

src/util/platform.rs

@@ -337,7 +337,37 @@ pub fn process_specialisation(
 }
 
 /// Execute common actions for a rebuild operation across platforms
-/// This unifies the core workflow that was previously duplicated across platforms
+///
+/// This function handles the core workflow for building and managing system
+/// configurations across different platforms (`NixOS`, Darwin, Home Manager).
+/// It unifies what would otherwise be duplicated across platform-specific modules.
+///
+/// The function takes care of:
+/// 1. Properly configuring the attribute path based on platform type
+/// 2. Building the configuration
+/// 3. Handling specialisations where applicable
+/// 4. Comparing the new configuration with the current one
+///
+/// # Arguments
+///
+/// * `installable` - The Nix installable representing the configuration
+/// * `config_type` - The configuration type (e.g., "nixosConfigurations", "darwinConfigurations")
+/// * `extra_path` - Additional path elements for the attribute path
+/// * `config_name` - Optional hostname or configuration name
+/// * `out_path` - Output path for the build result
+/// * `extra_args` - Additional arguments to pass to the build command
+/// * `builder` - Optional remote builder to use
+/// * `message` - Message to display during the build process
+/// * `no_nom` - Whether to disable nix-output-monitor
+/// * `specialisation_path` - Path to read specialisations from
+/// * `no_specialisation` - Whether to ignore specialisations
+/// * `specialisation` - Optional explicit specialisation to use
+/// * `current_profile` - Path to the current system profile for comparison
+/// * `skip_compare` - Whether to skip comparing the new and current configuration
+///
+/// # Returns
+///
+/// The path to the built configuration, which can be used for activation
 pub fn handle_rebuild_workflow(
     installable: Installable,
     config_type: &str,
@@ -379,7 +409,7 @@ pub fn handle_rebuild_workflow(
         {
             // All darwin configurations expose their outputs under system.build
             let toplevel_path = ["config", "system", "build"];
-            attribute.extend(toplevel_path.iter().map(|s| s.to_string()));
+            attribute.extend(toplevel_path.iter().map(|s| (*s).to_string()));
 
             // Add the final component (usually "toplevel")
             if !extra_path.is_empty() {