Improve --help (#624)

src/cli/mod.rs

@@ -19,9 +19,11 @@ pub trait CommandExecute {
     async fn execute(self) -> eyre::Result<ExitCode>;
 }
 
-/// The Determinate Nix installer
-///
-/// Plans a Nix install, prompts for confirmation, then executes it
+/**
+The Determinate Nix installer
+
+A fast, friendly, and reliable tool to help you use Nix with Flakes everywhere.
+*/
 #[derive(Debug, Parser)]
 #[clap(version)]
 pub struct NixInstallerCli {

src/cli/subcommand/install.rs

@@ -30,9 +30,13 @@ const EXISTING_INCOMPATIBLE_PLAN_GUIDANCE: &str = "\
     If you are using `nix-installer` in an automated curing process and seeing this message, consider pinning the version you use via https://github.com/DeterminateSystems/nix-installer#accessing-other-versions.\
 ";
 
-/// Execute an install (possibly using an existing plan)
-///
-/// To pass custom options, select a planner, for example `nix-installer install linux-multi --help`
+/**
+Install Nix using a planner
+
+By default, an appropriate planner is heuristically determined based on the system.
+
+Some planners have additional options which can be set from the planner's subcommand.
+*/
 #[derive(Debug, Parser)]
 #[command(args_conflicts_with_subcommands = true)]
 pub struct Install {

src/cli/subcommand/mod.rs

@@ -10,8 +10,8 @@ use self_test::SelfTest;
 #[allow(clippy::large_enum_variant)]
 #[derive(Debug, clap::Subcommand)]
 pub enum NixInstallerSubcommand {
-    Plan(Plan),
     Install(Install),
     Uninstall(Uninstall),
     SelfTest(SelfTest),
+    Plan(Plan),
 }

src/cli/subcommand/plan.rs

@@ -8,7 +8,11 @@ use owo_colors::OwoColorize;
 
 use crate::cli::CommandExecute;
 
-/// Plan an install that can be repeated on an identical host later
+/**
+Emit a JSON install plan that can be manually edited before execution
+
+Primarily intended for development, debugging, and handling install cases.
+*/
 #[derive(Debug, Parser)]
 pub struct Plan {
     #[clap(subcommand)]

src/cli/subcommand/self_test.rs

@@ -4,7 +4,7 @@ use clap::Parser;
 
 use crate::{cli::CommandExecute, NixInstallerError};
 
-/// Run a self test of Nix to ensure that the install worked.
+/// Run a self test of Nix to ensure that an install is working
 #[derive(Debug, Parser)]
 pub struct SelfTest {}
 

src/cli/subcommand/uninstall.rs

@@ -17,7 +17,7 @@ use rand::Rng;
 
 use crate::cli::{interaction, CommandExecute};
 
-/// Uninstall a previously installed Nix (only `nix-installer` done installs supported)
+/// Uninstall a previously `nix-installer` installed Nix
 #[derive(Debug, Parser)]
 pub struct Uninstall {
     #[clap(

src/planner/linux.rs

@@ -17,7 +17,7 @@ use which::which;
 
 use super::ShellProfileLocations;
 
-/// A planner for Linux installs
+/// A planner for traditional, mutable Linux systems like Debian, RHEL, or Arch
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 #[cfg_attr(feature = "cli", derive(clap::Parser))]
 pub struct Linux {

src/planner/macos.rs

@@ -23,7 +23,7 @@ use crate::{
     Action, BuiltinPlanner,
 };
 
-/// A planner for MacOS (Darwin) installs
+/// A planner for MacOS (Darwin) systems
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 #[cfg_attr(feature = "cli", derive(clap::Parser))]
 pub struct Macos {

src/planner/mod.rs

@@ -165,17 +165,17 @@ dyn_clone::clone_trait_object!(Planner);
 #[cfg_attr(feature = "cli", derive(clap::Subcommand))]
 pub enum BuiltinPlanner {
     #[cfg(target_os = "linux")]
-    /// A planner for Linux installs
+    /// A planner for traditional, mutable Linux systems like Debian, RHEL, or Arch
     Linux(linux::Linux),
-    /// A planner MacOS (Darwin) for installs
-    #[cfg(target_os = "macos")]
-    Macos(macos::Macos),
-    /// A planner suitable for the Valve Steam Deck running SteamOS
+    /// A planner for the Valve Steam Deck running SteamOS
     #[cfg(target_os = "linux")]
     SteamDeck(steam_deck::SteamDeck),
-    /// A planner suitable for immutable distributions using ostree
+    /// A planner suitable for immutable systems using ostree, such as Fedora Silverblue
     #[cfg(target_os = "linux")]
     Ostree(ostree::Ostree),
+    /// A planner for MacOS (Darwin) systems
+    #[cfg(target_os = "macos")]
+    Macos(macos::Macos),
 }
 
 impl BuiltinPlanner {

src/planner/ostree.rs

@@ -21,7 +21,7 @@ use super::{
     ShellProfileLocations,
 };
 
-/// A planner for Linux installs
+/// A planner suitable for immutable systems using ostree, such as Fedora Silverblue
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 #[cfg_attr(feature = "cli", derive(clap::Parser))]
 pub struct Ostree {

src/planner/steam_deck.rs

@@ -117,6 +117,7 @@ use crate::{
 
 use super::ShellProfileLocations;
 
+/// A planner for the Valve Steam Deck running SteamOS
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 #[cfg_attr(feature = "cli", derive(clap::Parser))]
 pub struct SteamDeck {