From 737ade619a71557a86ffbeda2dfa6624ecb54516 Mon Sep 17 00:00:00 2001
From: Nicholas Wiles <nwiles@google.com>
Date: Sun, 15 Oct 2017 20:07:00 -0700
Subject: [PATCH] Add documentation for completion help strings.

---
 docs/bashcomplete.rst | 34 ++++++++++++++++++++++++++++++----
 1 file changed, 30 insertions(+), 4 deletions(-)

diff --git a/docs/bashcomplete.rst b/docs/bashcomplete.rst
index 1cbf4a5e6..220dfa185 100644
--- a/docs/bashcomplete.rst
+++ b/docs/bashcomplete.rst
@@ -12,9 +12,8 @@ Limitations
 
 Bash completion is only available if a script has been installed properly,
 and not executed through the ``python`` command.  For information about
-how to do that, see :ref:`setuptools-integration`.  Also, Click currently
-only supports completion for Bash. Zsh support is available through Zsh's
-bash completion compatibility mode.
+how to do that, see :ref:`setuptools-integration`.  Click currently
+only supports completion for Bash and Zsh.
 
 What it Completes
 -----------------
@@ -47,7 +46,7 @@ Here is an example of using a callback function to generate dynamic suggestions:
     import os
 
     def get_env_vars(ctx, args, incomplete):
-        return os.environ.keys()
+        return [k for k in os.environ.keys() if incomplete in k]
 
     @click.command()
     @click.argument("envvar", type=click.STRING, autocompletion=get_env_vars)
@@ -56,6 +55,33 @@ Here is an example of using a callback function to generate dynamic suggestions:
         click.echo('Value: %s' % os.environ[envvar])
 
 
+Completion help strings (ZSH only)
+----------------------------------
+
+ZSH supports showing documentation strings for completions. These are taken
+from the help parameters of options and subcommands. For dynamically generated
+completions a help string can be provided by returning a tuple instead of a
+string. The first element of the tuple is the completion and the second is the
+help string to display.
+
+Here is an example of using a callback function to generate dynamic suggestions with a help strings:
+
+.. click:example::
+
+    import os
+
+    def get_colors(ctx, args, incomplete):
+        colors = [('red', 'help string for the color red'),
+                  ('blue', 'help string for the color blue'),
+                  ('green', 'help string for the color green')]
+        return [c for c in colors if incomplete in c[0]]
+
+    @click.command()
+    @click.argument("color", type=click.STRING, autocompletion=get_colors)
+    def cmd1(color):
+        click.echo('Chosen color is %s' % color)
+
+
 Activation
 ----------