Improve zsh completion documentation

shell_completions.md

@@ -33,11 +33,16 @@ MacOS:
 
 Zsh:
 
-$ source <(yourprogram completion zsh)
+# If shell completion is not already enabled in your environment you will need
+# to enable it.  You can execute the following once:
+
+$ echo "autoload -U compinit; compinit" >> ~/.zshrc
 
 # To load completions for each session, execute once:
 $ yourprogram completion zsh > "${fpath[1]}/_yourprogram"
 
+# You will need to start a new shell for this setup to take effect.
+
 Fish:
 
 $ yourprogram completion fish | source
@@ -363,7 +368,7 @@ Please refer to [Bash Completions](bash_completions.md) for details.
 
 Cobra supports native Zsh completion generated from the root `cobra.Command`.
 The generated completion script should be put somewhere in your `$fpath` and be named
-`_<yourProgram>`.
+`_<yourProgram>`.  You will need to start a new shell for the completions to become available.
 
 Zsh supports descriptions for completions. Cobra will provide the description automatically,
 based on usage information. Cobra provides a way to completely disable such descriptions by

zsh_completions.md

@@ -22,6 +22,7 @@ See further below for more details on these deprecations.
 |Old behavior|New behavior|
 |---|---|
 |No file completion by default (opposite of bash)|File completion by default; use `ValidArgsFunction` with `ShellCompDirectiveNoFileComp` to turn off file completion on a per-argument basis|
+|Completion of flag names without the `-` prefix having been typed|Flag names are only completed if the user has typed the first `-`|
 `cmd.MarkZshCompPositionalArgumentFile(pos, []string{})` used to turn on file completion on a per-argument position basis|File completion for all arguments by default; `cmd.MarkZshCompPositionalArgumentFile()` is **deprecated** and silently ignored|
 |`cmd.MarkZshCompPositionalArgumentFile(pos, glob[])` used to turn on file completion **with glob filtering** on a per-argument position basis (zsh-specific)|`cmd.MarkZshCompPositionalArgumentFile()` is **deprecated** and silently ignored; use `ValidArgsFunction` with `ShellCompDirectiveFilterFileExt` for file **extension** filtering (not full glob filtering)|
 |`cmd.MarkZshCompPositionalArgumentWords(pos, words[])` used to provide completion choices on a per-argument position basis (zsh-specific)|`cmd.MarkZshCompPositionalArgumentWords()` is **deprecated** and silently ignored; use `ValidArgsFunction` to achieve the same behavior|