Document --watch-when-idle much more thoroughly

completions/zsh

@@ -11,13 +11,14 @@ cmd="$words[1]"
 args=(
   '(-c --clear)'{-c,--clear}'[Clear screen before executing command]'
   '(-h --help)'{-h,--help}'[Prints help information]'
-  '--shell=[Change the wrapping shell, or `none` to disable]'
+  '--shell=[Change the wrapping shell, or set to none to disable]'
   '--no-shell[Deprecated, use --shell=none]'
   '-n[Shorthand for --shell=none]'
   '--no-environment[Do not set WATCHEXEC_*_PATH environment variables for command]'
   '--no-meta[Ignore metadata changes]'
   '(-p --postpone)'{-p,--postpone}'[Wait until first change to execute command]'
   '(-r --restart)'{-r,--restart}'[Restart the process if it''s still running]'
+  '(-W --watch-when-idle)'{-W,--watch-when-idle}'[Ignore events while the command is still running]'
   '(-V --version)'{-V,--version}'[Prints version information]'
   '(-v --verbose)'{-v,--verbose}'[Print debugging messages to stderr]'
   '--changes-only[Print changed paths to stderr for pattern debugging]'

doc/watchexec.1.ronn

@@ -54,7 +54,9 @@ Monitor a specific path for changes. By default, the current working directory i
 Terminates the command if it is still running when subsequent file modifications are detected. By default, sends `SIGTERM`; use `--signal` to change that.
 
 * `-W`, `--watch-when-idle`:
-Ignore events while the process is still running.
+Ignore events while the process is still running. This is distinct from `--restart` in that with this option, events received while the command is running will not trigger a new run immediately after the current command is done.
+
+This behaviour will become the default in v2.0.
 
 * `-c`, `--clear`:
 Clears the screen before executing <command>.

src/args.rs

@@ -130,7 +130,7 @@ where
                  .long("no-environment"))
         .arg(Arg::with_name("once").short("1").hidden(true))
         .arg(Arg::with_name("watch-when-idle")
-                 .help("Ignore events while the process is still running")
+                 .help("Ignore events while the process is still running. This is distinct from `--restart` in that with this option, events received while the command is running will not trigger a new run immediately after the current command is done. Will become the default in 2.0.")
                  .short("W")
                  .long("watch-when-idle"));