Merge pull request #915 from python-cmd2/decorator_order

Added documentation about decorator order and updated an example

1 files changed, 35 insertions, 0 deletions

diff --git a/docs/features/argument_processing.rst b/docs/features/argument_processing.rst
index 204c2876..18c5b7ca 100644
--- a/docs/features/argument_processing.rst
+++ b/docs/features/argument_processing.rst
@@ -347,3 +347,38 @@ class which inherits from ``argparse.ArgumentParser`` and improves error and
 help output.
 
 
+Decorator Order
+---------------
+
+If you are using custom decorators in combination with either
+``@cmd2.with_argparser`` or ``@cmd2.with_argparser_and_unknown_args``, then the
+order of your custom decorator(s) relative to the ``cmd2`` decorator matters
+when it comes to runtime behavior and ``argparse`` errors.  There is nothing
+``cmd2``-specific here, this is just a side-effect of how decorators work in
+Python.  To learn more about how decorators work, see decorator_primer_.
+
+If you want your custom decorator's runtime behavior to occur in the case of
+an ``argparse`` error, then that decorator needs to go **after** the
+``argparse`` one, e.g.::
+
+    @cmd2.with_argparser(foo_parser)
+    @my_decorator
+    def do_foo(self, args: argparse.Namespace) -> None:
+        """foo docs"""
+        pass
+
+However, if you do NOT want the customer decorator runtime behavior to occur
+even in the case of an `argparse` error, then that decorator needs to go
+**before** the ``arpgarse`` one, e.g.::
+
+    @my_decorator
+    @cmd2.with_argparser(bar_parser)
+    def do_bar(self, args: argparse.Namespace) -> None:
+        """bar docs"""
+        pass
+
+The help_categories_ example demonstrates both above cases in a concrete
+fashion.
+
+.. _decorator_primer: https://realpython.com/primer-on-python-decorators
+.. _help_categories: https://github.com/python-cmd2/cmd2/blob/master/examples/help_categories.py