Improved documentation for argument parsing decorators

Also:
- Improved type hinting for these decorators

2 files changed, 38 insertions, 13 deletions

diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py
index f8dd63d3..669c4a5a 100644
--- a/cmd2/cmd2.py
+++ b/cmd2/cmd2.py
@@ -173,11 +173,17 @@ def with_category(category: str) -> Callable:
     return cat_decorator
 
 
-def with_argument_list(func: Callable, preserve_quotes: bool=False) -> Callable:
-    """A decorator to alter the arguments passed to a do_* cmd2
-    method. Default passes a string of whatever the user typed.
-    With this decorator, the decorated method will receive a list
-    of arguments parsed from user input using shlex.split()."""
+def with_argument_list(func: Callable[[Statement], Optional[bool]],
+                       preserve_quotes: bool=False) -> Callable[[List], Optional[bool]]:
+    """A decorator to alter the arguments passed to a do_* cmd2 method. Default passes a string of whatever the user
+    typed. With this decorator, the decorated method will receive a list of arguments parsed from user input using
+    shlex.split().
+
+    :param func: do_* method this decorator is wrapping
+    :param preserve_quotes: if True, then arguments passed to arparse maintain their quotes
+    :return: function that gets passed a list of argument strings
+    """
+    """"""
     import functools
 
     @functools.wraps(func)
@@ -189,18 +195,19 @@ def with_argument_list(func: Callable, preserve_quotes: bool=False) -> Callable:
     return cmd_wrapper
 
 
-def with_argparser_and_unknown_args(argparser: argparse.ArgumentParser, preserve_quotes: bool=False) -> Callable:
+def with_argparser_and_unknown_args(argparser: argparse.ArgumentParser, preserve_quotes: bool=False) -> \
+        Callable[[argparse.Namespace, List], Optional[bool]]:
     """A decorator to alter a cmd2 method to populate its ``args`` argument by parsing arguments with the given
     instance of argparse.ArgumentParser, but also returning unknown args as a list.
 
     :param argparser: unique instance of ArgumentParser
-    :param preserve_quotes: if True, then the arguments passed to arparse be maintain their quotes
-    :return: function that gets passed parsed args and a list of unknown args
+    :param preserve_quotes: if True, then arguments passed to arparse maintain their quotes
+    :return: function that gets passed argparse-parsed args and a list of unknown argument strings
     """
     import functools
 
     # noinspection PyProtectedMember
-    def arg_decorator(func: Callable):
+    def arg_decorator(func: Callable[[Statement], Optional[bool]]):
         @functools.wraps(func)
         def cmd_wrapper(instance, cmdline):
             lexed_arglist = parse_quoted_string(cmdline, preserve_quotes)
@@ -230,18 +237,19 @@ def with_argparser_and_unknown_args(argparser: argparse.ArgumentParser, preserve
     return arg_decorator
 
 
-def with_argparser(argparser: argparse.ArgumentParser, preserve_quotes: bool=False) -> Callable:
+def with_argparser(argparser: argparse.ArgumentParser,
+                   preserve_quotes: bool=False) -> Callable[[argparse.Namespace], Optional[bool]]:
     """A decorator to alter a cmd2 method to populate its ``args`` argument by parsing arguments
     with the given instance of argparse.ArgumentParser.
 
     :param argparser: unique instance of ArgumentParser
-    :param preserve_quotes: if True, then the arguments passed to arparse be maintain their quotes
-    :return: function that gets passed parsed args
+    :param preserve_quotes: if True, then arguments passed to arparse maintain their quotes
+    :return: function that gets passed the argparse-parsed args
     """
     import functools
 
     # noinspection PyProtectedMember
-    def arg_decorator(func: Callable):
+    def arg_decorator(func: Callable[[Statement], Optional[bool]]):
         @functools.wraps(func)
         def cmd_wrapper(instance, cmdline):
             lexed_arglist = parse_quoted_string(cmdline, preserve_quotes)
diff --git a/docs/argument_processing.rst b/docs/argument_processing.rst
index 8931c60b..7e8d8f3e 100644
--- a/docs/argument_processing.rst
+++ b/docs/argument_processing.rst
@@ -21,6 +21,20 @@ processing decorators in your ``cmd2`` applications.
 .. _argprint: https://github.com/python-cmd2/cmd2/blob/master/examples/arg_print.py
 .. _decorator: https://github.com/python-cmd2/cmd2/blob/master/examples/decorator_example.py
 
+
+Decorators provided by cmd2 for argument processing
+===================================================
+``cmd2`` provides the following decorators for assisting with parsing arguments passed to commands:
+
+.. automethod:: cmd2.cmd2.with_argument_list
+.. automethod:: cmd2.cmd2.with_argparser
+.. automethod:: cmd2.cmd2.with_argparser_and_unknown_args
+
+All of these decorators accept an optional **preserve_quotes** argument which defaults to ``False``.
+Setting this argument to ``True`` is useful for cases where you are passing the arguments to another
+command which might have its own argument parsing.
+
+
 Using the argument parser decorator
 ===================================
 
@@ -402,3 +416,6 @@ See the subcommands_ and tab_autocompletion_ example to learn more about how to
 
 .. _subcommands: https://github.com/python-cmd2/cmd2/blob/master/examples/subcommands.py
 .. _tab_autocompletion: https://github.com/python-cmd2/cmd2/blob/master/examples/tab_autocompletion.py
+
+
+