From a2078e3703a01eb83284bf5a50bd93862eee348d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fe=CC=81lix=20Saparelli?= <felix@passcod.name>
Date: Sat, 17 Apr 2021 01:20:30 +1200
Subject: [PATCH] Document the semantics of the Shell variants

---
 src/config.rs  | 27 ++++++++++++++++++++++++---
 src/process.rs | 25 +++++++++++++++++++++++--
 2 files changed, 47 insertions(+), 5 deletions(-)

diff --git a/src/config.rs b/src/config.rs
index f7bcb14..619c319 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -24,54 +24,75 @@ use crate::run::OnBusyUpdate;
 #[builder(build_fn(validate = "Self::validate"))]
 #[non_exhaustive]
 pub struct Config {
-    /// Command to execute in popen3 format (first program, rest arguments).
+    /// Command to execute.
+    ///
+    /// When `shell` is [`Shell::None`], this is expected to be in “popen3”
+    /// format: first program, rest arguments. Otherwise, all elements will be
+    /// joined together with a single space and passed to the shell. More
+    /// control can then be obtained by providing a 1-element vec, and doing
+    /// your own joining and/or escaping there.
     pub cmd: Vec<String>,
+
     /// List of paths to watch for changes.
     pub paths: Vec<PathBuf>,
+
     /// Positive filters (trigger only on matching changes). Glob format.
     #[builder(default)]
     pub filters: Vec<String>,
+
     /// Negative filters (do not trigger on matching changes). Glob format.
     #[builder(default)]
     pub ignores: Vec<String>,
+
     /// Clear the screen before each run.
     #[builder(default)]
     pub clear_screen: bool,
+
     /// If Some, send that signal (e.g. SIGHUP) to the command on change.
     #[builder(default)]
     pub signal: Option<String>,
+
     /// Specify what to do when receiving updates while the command is running.
     #[builder(default)]
     pub on_busy_update: OnBusyUpdate,
+
     /// Interval to debounce the changes.
     #[builder(default = "Duration::from_millis(150)")]
     pub debounce: Duration,
+
     /// Run the commands right after starting.
     #[builder(default = "true")]
     pub run_initially: bool,
+
     /// Specify the shell to use.
     #[builder(default)]
     pub shell: Shell,
+
     /// Ignore metadata changes.
     #[builder(default)]
     pub no_meta: bool,
+
     /// Do not set WATCHEXEC_*_PATH environment variables for the process.
     #[builder(default)]
     pub no_environment: bool,
+
     /// Skip auto-loading .gitignore files
     #[builder(default)]
     pub no_vcs_ignore: bool,
+
     /// Skip auto-loading .ignore files
     #[builder(default)]
     pub no_ignore: bool,
+
     /// For testing only, always set to false.
-    #[builder(setter(skip))]
-    #[builder(default)]
+    #[builder(setter(skip), default)]
     #[doc(hidden)]
     pub once: bool,
+
     /// Force using the polling backend.
     #[builder(default)]
     pub poll: bool,
+
     /// Interval for polling.
     #[builder(default = "Duration::from_secs(1)")]
     pub poll_interval: Duration,
diff --git a/src/process.rs b/src/process.rs
index 35f83b2..29061c4 100644
--- a/src/process.rs
+++ b/src/process.rs
@@ -2,20 +2,41 @@
 
 use crate::error::Result;
 use crate::pathop::PathOp;
-use std::collections::{HashMap, HashSet};
-use std::path::PathBuf;
+use std::{collections::{HashMap, HashSet},
+path::PathBuf,
+process::Command};
 
 /// Shell to use to run commands.
 ///
 /// `Cmd` and `Powershell` are special-cased because they have different calling
 /// conventions. Also `Cmd` is only available in Windows, while `Powershell` is
 /// also available on unices (provided the end-user has it installed, of course).
+///
+/// See [`Config.cmd`][crate::config::Config] for the semantics of `None` vs the
+/// other options.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum Shell {
+    /// Use no shell, and execute the command directly.
     None,
+
+    /// Use the given string as a unix shell invocation.
+    ///
+    /// This means two things:
+    /// - the program is invoked with `-c` followed by the command, and
     Unix(String),
+
+    /// Use the Windows CMD.EXE shell.
+    ///
+    /// This is invoked with `/C` followed by the command.
     #[cfg(windows)]
     Cmd,
+
+    /// Use Powershell, on Windows or elsewhere.
+    ///
+    /// This is invoked with `-Command` followed by the command.
+    ///
+    /// This is preferred over `Unix("pwsh")`, though that will also work
+    /// on unices due to Powershell supporting the `-c` short option.
     Powershell,
 }