Merge pull request #847 from python-cmd2/generating_output_docs

Generating output docs

1 files changed, 13 insertions, 3 deletions

diff --git a/cmd2/ansi.py b/cmd2/ansi.py
index b3dd7cc1..d3af525a 100644
--- a/cmd2/ansi.py
+++ b/cmd2/ansi.py
@@ -94,7 +94,9 @@ def strip_style(text: str) -> str:
 def style_aware_wcswidth(text: str) -> int:
     """
     Wrap wcswidth to make it compatible with strings that contains ANSI style sequences
+
     :param text: the string being measured
+    :return: the width of the string when printed to the terminal
     """
     # Strip ANSI style sequences since they cause wcswidth to return -1
     return wcswidth(strip_style(text))
@@ -103,6 +105,7 @@ def style_aware_wcswidth(text: str) -> int:
 def style_aware_write(fileobj: IO, msg: str) -> None:
     """
     Write a string to a fileobject and strip its ANSI style sequences if required by allow_style setting
+
     :param fileobj: the file object being written to
     :param msg: the string being written
     """
@@ -115,9 +118,10 @@ def style_aware_write(fileobj: IO, msg: str) -> None:
 def fg_lookup(fg_name: str) -> str:
     """
     Look up ANSI escape codes based on foreground color name.
+
     :param fg_name: foreground color name to look up ANSI escape code(s) for
     :return: ANSI escape code(s) associated with this color
-    :raises ValueError if the color cannot be found
+    :raises ValueError: if the color cannot be found
     """
     try:
         ansi_escape = FG_COLORS[fg_name.lower()]
@@ -129,9 +133,10 @@ def fg_lookup(fg_name: str) -> str:
 def bg_lookup(bg_name: str) -> str:
     """
     Look up ANSI escape codes based on background color name.
+
     :param bg_name: background color name to look up ANSI escape code(s) for
     :return: ANSI escape code(s) associated with this color
-    :raises ValueError if the color cannot be found
+    :raises ValueError: if the color cannot be found
     """
     try:
         ansi_escape = BG_COLORS[bg_name.lower()]
@@ -193,8 +198,13 @@ def style(text: Any, *, fg: str = '', bg: str = '', bold: bool = False,
 # These can be altered to suit an application's needs and only need to be a
 # function with the following structure: func(str) -> str
 style_success = functools.partial(style, fg='green')
+"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify success"""
+
 style_warning = functools.partial(style, fg='bright_yellow')
+"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify a warning"""
+
 style_error = functools.partial(style, fg='bright_red')
+"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify an error"""
 
 
 def async_alert_str(*, terminal_columns: int, prompt: str, line: str, cursor_offset: int, alert_msg: str) -> str:
@@ -255,6 +265,6 @@ def set_title_str(title: str) -> str:
     """Get the required string, including ANSI escape codes, for setting window title for the terminal.
 
     :param title: new title for the window
-    :return string to write to sys.stderr in order to set the window title to the desired test
+    :return: string to write to sys.stderr in order to set the window title to the desired test
     """
     return colorama.ansi.set_title(title)