Updated documentation

Author: kmvanbrunt

CHANGELOG.md

@@ -6,6 +6,9 @@
     also be colored.
         * `help_error` - the error that prints when no help information can be found
         * `default_error` - the error that prints when a non-existent command is run
+    * The `with_argparser` decorators now add a Statement object to the `argparse.Namespace` object they pass
+    to the `do_*` functions. It is stored in an attribute called `__statement__`. This can be useful if a command
+    function needs to know the command line for things like logging.
 * Potentially breaking changes
     * The following commands now write to stderr instead of stdout when printing an error. This will make catching
     errors easier in pyscript.

cmd2/cmd2.py

@@ -199,7 +199,7 @@ def with_argparser_and_unknown_args(argparser: argparse.ArgumentParser, preserve
     :param preserve_quotes: if True, then arguments passed to argparse maintain their quotes
     :return: function that gets passed argparse-parsed args in a Namespace and a list of unknown argument strings
              A member called __statement__ is added to the Namespace to provide command functions access to the
-             Statement object. This can be useful when knowledge of the command line is needed.
+             Statement object. This can be useful if the command function needs to know the command line.
 
     """
     import functools
@@ -249,7 +249,7 @@ def with_argparser(argparser: argparse.ArgumentParser,
     :param preserve_quotes: if True, then arguments passed to argparse maintain their quotes
     :return: function that gets passed the argparse-parsed args in a Namespace
              A member called __statement__ is added to the Namespace to provide command functions access to the
-             Statement object. This can be useful when knowledge of the command line is needed.
+             Statement object. This can be useful if the command function needs to know the command line.
     """
     import functools
 

cmd2/parsing.py

@@ -348,9 +348,10 @@ def tokenize(self, line: str, expand: bool = True) -> List[str]:
         Lex a string into a list of tokens. Shortcuts and aliases are expanded and comments are removed
 
         :param line: the command line being lexed
-        :param expand: if True, then aliases and shortcuts will be expanded
-                       set this to False if the first token does not need to be expanded
-                       because the command name is already known (Defaults to True)
+        :param expand: If True, then aliases and shortcuts will be expanded.
+                       Set this to False if no expansion should occur because the command name is already known.
+                       Otherwise the command could be expanded if it matched an alias name. This is for cases where
+                       a do_* function was called manually (e.g do_help('alias').
         :return: A list of tokens
         :raises ValueError if there are unclosed quotation marks.
         """
@@ -377,9 +378,10 @@ def parse(self, line: str, expand: bool = True) -> Statement:
         redirection directives.
 
         :param line: the command line being parsed
-        :param expand: if True, then aliases and shortcuts will be expanded
-                       set this to False if the first token does not need to be expanded
-                       because the command name is already known (Defaults to True)
+        :param expand: If True, then aliases and shortcuts will be expanded.
+                       Set this to False if no expansion should occur because the command name is already known.
+                       Otherwise the command could be expanded if it matched an alias name. This is for cases where
+                       a do_* function was called manually (e.g do_help('alias').
         :return: A parsed Statement
         :raises ValueError if there are unclosed quotation marks
         """