Embedded examples and cross-links for categorize() and with_category()

2 files changed, 16 insertions, 1 deletions

diff --git a/cmd2/decorators.py b/cmd2/decorators.py
index a8babcac..e9aff0eb 100644
--- a/cmd2/decorators.py
+++ b/cmd2/decorators.py
@@ -19,6 +19,9 @@ def with_category(category: str) -> Callable:
     >>>   @cmd2.with_category('Text Functions')
     >>>   def do_echo(self, args)
     >>>     self.poutput(args)
+
+    For an alternative approach to categorizing commands using a function, see
+    :func:`~cmd2.utils.categorize`
     """
     def cat_decorator(func):
         from .utils import categorize
diff --git a/cmd2/utils.py b/cmd2/utils.py
index 971a22ce..2f0e8bcf 100644
--- a/cmd2/utils.py
+++ b/cmd2/utils.py
@@ -969,10 +969,22 @@ def get_styles_in_text(text: str) -> Dict[int, str]:
 def categorize(func: Union[Callable, Iterable[Callable]], category: str) -> None:
     """Categorize a function.
 
-    The help command output will group this function under the specified category heading
+    The help command output will group the passed function under the
+    specified category heading
 
     :param func: function or list of functions to categorize
     :param category: category to put it in
+
+    :Example:
+
+    >>> class MyApp(cmd2.Cmd):
+    >>>   def do_echo(self, arglist):
+    >>>     self.poutput(' '.join(arglist)
+    >>>
+    >>>   utils.categorize(do_echo, "Text Processing")
+
+    For an alternative approach to categorizing commands using a decorator, see
+    :func:`~cmd2.decorators.with_category`
     """
     if isinstance(func, Iterable):
         for item in func: