diff --git a/clap_generate/src/generators/shells/fish.rs b/clap_generate/src/generators/shells/fish.rs
index 8e555c86375e..823224624c60 100644
--- a/clap_generate/src/generators/shells/fish.rs
+++ b/clap_generate/src/generators/shells/fish.rs
@@ -136,6 +136,7 @@ fn value_completion(option: &Arg) -> String {
     if let Some(ref data) = option.get_possible_values() {
         format!(" -r -f -a \"{}\"", data.join(" "))
     } else {
+        // NB! If you change this, please also update the table in `ValueHint` documentation.
         match option.get_value_hint() {
             ValueHint::Unknown => " -r",
             // fish has no built-in support to distinguish these
diff --git a/clap_generate/src/generators/shells/zsh.rs b/clap_generate/src/generators/shells/zsh.rs
index 780f249e9113..8d8aea1819f7 100644
--- a/clap_generate/src/generators/shells/zsh.rs
+++ b/clap_generate/src/generators/shells/zsh.rs
@@ -342,6 +342,7 @@ fn value_completion(arg: &Arg) -> Option<String> {
                 .join(" ")
         ))
     } else {
+        // NB! If you change this, please also update the table in `ValueHint` documentation.
         Some(
             match arg.get_value_hint() {
                 ValueHint::Unknown => {
diff --git a/src/build/arg/value_hint.rs b/src/build/arg/value_hint.rs
index 4731fb879b36..ccc989322a13 100644
--- a/src/build/arg/value_hint.rs
+++ b/src/build/arg/value_hint.rs
@@ -1,6 +1,24 @@
 use std::str::FromStr;
 
 /// Provides hints about argument types for shell command completion.
+///
+/// See the `clap_generate` crate for completion script generation.
+///
+/// Overview of which hints are supported by which shell:
+///
+/// | Hint                   | zsh | fish    |
+/// | ---------------------- | --- | ------- |
+/// | `AnyPath`              | Yes | Yes     |
+/// | `FilePath`             | Yes | Yes     |
+/// | `DirPath`              | Yes | Yes     |
+/// | `ExecutablePath`       | Yes | Partial |
+/// | `CommandName`          | Yes | Yes     |
+/// | `CommandString`        | Yes | Partial |
+/// | `CommandWithArguments` | Yes |         |
+/// | `Username`             | Yes | Yes     |
+/// | `Hostname`             | Yes | Yes     |
+/// | `Url`                  | Yes |         |
+/// | `EmailAddress`         | Yes |         |
 #[derive(Debug, PartialEq, Copy, Clone)]
 pub enum ValueHint {
     /// Default value if hint is not specified. Follows shell default behavior, which is usually
@@ -20,15 +38,21 @@ pub enum ValueHint {
     CommandName,
     /// A single string containing a command and its arguments.
     CommandString,
-    /// A command and each argument as multiple strings. Common for command wrappers.
+    /// Capture the remaining arguments as a command name and arguments for that command. This is
+    /// common when writing shell wrappers that execute anther command, for example `sudo` or `env`.
     ///
-    /// This hint is special, the argument must be a positional argument and use `.multiple(true)`.
-    /// It's also recommended to use `AppSettings::TrailingVarArg` to avoid confusion about which
-    /// command the following options belong to.
+    /// This hint is special, the argument must be a positional argument and have
+    /// [`.multiple(true)`] and App must use [`AppSettings::TrailingVarArg`]. The result is that the
+    /// command line `my_app ls -la /` will be parsed as `["ls", "-la", "/"]` and clap won't try to
+    /// parse the `-la` argument itself.
+    ///
+    /// [`.multiple(true)`]: ./struct.Arg.html#method.multiple
+    /// [`AppSettings::TrailingVarArg`]: ./enum.AppSettings.html#variant.TrailingVarArg
     CommandWithArguments,
     /// Name of a local operating system user.
     Username,
     /// Host name of a computer.
+    /// Shells usually parse `/etc/hosts` and `.ssh/known_hosts` to complete hostnames.
     Hostname,
     /// Complete web address.
     Url,