fix & document description vs help, metavar vs dest

docs/index.md

@@ -97,8 +97,11 @@ Not working?
 - Ensure that `prog` is set:
     - if using [`options.entry_points.console_scripts=MY_PROG=...`](https://setuptools.pypa.io/en/latest/userguide/entry_point.html), then ensure the main parser's `prog` matches `argparse.ArgumentParser(prog="MY_PROG")` or override it using `shtab MY_PROG.get_main_parser --prog=MY_PROG`.
     - if executing a script file `./MY_PROG.py` (with a [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) `#!/usr/bin/env python`) directly, then use `argparse.ArgumentParser(prog="MY_PROG.py")` or override it using `shtab MY_PROG.get_main_parser --prog=MY_PROG.py`.
-- Ensure that all arguments have `help` messages (`parser.add_argument('positional', help="documented; i.e. not hidden")`).
-- Path completion is disabled by default, and must be enabled explicitly (`parser.add_argument('positional').complete = shtab.FILE`).
+- Any argument with `help=argparse.SUPPRESS` is skipped.
+- Default completion (when no choices are specified) is disabled. Enable it explicitly via e.g. `parser.add_argument('positional').complete = shtab.FILE`.
+- Some shells (e.g. `zsh`, `fish`) print information during tab completion:
+    - subparser `description` takes precedence over `help`.
+    - argument `metavar` takes precedence over `dest`.
 - [Ask a general question on StackOverflow](https://stackoverflow.com/questions/tagged/shtab).
 - [Report bugs and open feature requests on GitHub][issues].
 

examples/customcomplete.py

@@ -1,4 +1,4 @@
 #!/usr/bin/env python
 """
 `argparse`-based CLI app with custom file completion as well as subparsers.
 
@@ -11,7 +11,7 @@
 
 def process(args):
     print(f"received <token>={args.token} [<suffix>={args.suffix}]"
-          f" --input-file={args.input_file} --output-name={args.output_name}"
+          f" --input-file={args.input_name} --output-name={args.output_name}"
           f" --compose-file={args.compose_file} --hidden-opt={args.hidden_opt}")
 
 
@@ -26,7 +26,7 @@
     # WARNING: shtab.cmd is (re)run by your shell on each tab press, so could be slow
     parser.add_argument("token").complete = shtab.cmd("head -c5 /dev/random | base32")
     # file tab completion builtin shortcut
-    parser.add_argument("-i", "--input-file").complete = shtab.FILE
+    parser.add_argument("-i", "--input-file", dest="input_name").complete = shtab.FILE
     # directory tab completion builtin shortcut
     parser.add_argument(
         "-o",
@@ -35,8 +35,9 @@
               " accidentally overwriting existing files."),
     ).complete = shtab.DIRECTORY
     # glob pattern tab completion builtin shortcut
-    parser.add_argument("--compose-file").complete = shtab.glob("docker-compose*.yml",
-                                                                "docker-compose*.yaml")
+    parser.add_argument("--compose-file",
+                        metavar="yaml").complete = shtab.glob("docker-compose*.yml",
+                                                              "docker-compose*.yaml")
     parser.add_argument("suffix", choices=['json', 'csv'], default='json', nargs='?',
                         help="Output format")
     # help=None or argparse.SUPPRESS to exclude from CLI --help & completions