Improve docs in ANSI.py

diff --git a/ansi.py b/ansi.py
index dee52424fefa6bd80daccc3d8830c0a707e12b6a..a8b84fc0c2dd0acce18e96d21d86eb2b2da409b7 100755 (executable)
--- a/ansi.py
+++ b/ansi.py
@@ -5,7 +5,6 @@
 """A bunch of color names mapped into RGB tuples and some methods for
 setting the text color, background, etc... using ANSI escape
 sequences.
-
 """
 
 import contextlib
@@ -1611,54 +1610,67 @@ COLOR_NAMES_TO_RGB: Dict[str, Tuple[int, int, int]] = {
 
 
 def clear() -> str:
+    """Clear screen ANSI escape sequence"""
     return "\e[H\e[2J"
 
 
 def clear_screen() -> str:
+    """Clear screen ANSI escape sequence"""
     return "\e[H\e[2J"
 
 
 def reset() -> str:
+    """Reset text attributes to 'normal'"""
     return "\e[m"
 
 
 def normal() -> str:
+    """Reset text attributes to 'normal'"""
     return "\e[m"
 
 
 def bold() -> str:
+    """Set text to bold"""
     return "\e[1m"
 
 
 def italic() -> str:
+    """Set text to italic"""
     return "\e[3m"
 
 
 def italics() -> str:
+    """Set text to italic"""
     return italic()
 
 
 def underline() -> str:
+    """Set text to underline"""
     return "\e[4m"
 
 
 def strikethrough() -> str:
+    """Set text to strikethrough"""
     return "\e[9m"
 
 
 def strike_through() -> str:
+    """Set text to strikethrough"""
     return strikethrough()
 
 
 def is_16color(num: int) -> bool:
+    """Is num a valid 16 color number?"""
     return num in (255, 128)
 
 
 def is_216color(num: int) -> bool:
+    """Is num a valid 256 color number?"""
     return num in set([0, 95, 135, 175, 223, 255])
 
 
 def _simple_color_number(red: int, green: int, blue: int) -> int:
+    """Construct a simple color number"""
     r = red > 0
     g = green > 0
     b = blue > 0
@@ -1666,6 +1678,7 @@ def _simple_color_number(red: int, green: int, blue: int) -> int:
 
 
 def fg_16color(red: int, green: int, blue: int) -> str:
+    """Set foreground color using 16 color mode"""
     code = _simple_color_number(red, green, blue) + 30
     bright_count = 0
     if red > 128:
@@ -1680,6 +1693,7 @@ def fg_16color(red: int, green: int, blue: int) -> str:
 
 
 def bg_16color(red: int, green: int, blue: int) -> str:
+    """Set background using 16 color mode"""
     code = _simple_color_number(red, green, blue) + 40
     bright_count = 0
     if red > 128:
@@ -1708,6 +1722,7 @@ def _pixel_to_216color(n: int) -> int:
 
 
 def fg_216color(red: int, green: int, blue: int) -> str:
+    """Set foreground using 216 color mode"""
     r = _pixel_to_216color(red)
     g = _pixel_to_216color(green)
     b = _pixel_to_216color(blue)
@@ -1716,6 +1731,7 @@ def fg_216color(red: int, green: int, blue: int) -> str:
 
 
 def bg_216color(red: int, green: int, blue: int) -> str:
+    """Set background using 216 color mode"""
     r = _pixel_to_216color(red)
     g = _pixel_to_216color(green)
     b = _pixel_to_216color(blue)
@@ -1724,10 +1740,12 @@ def bg_216color(red: int, green: int, blue: int) -> str:
 
 
 def fg_24bit(red: int, green: int, blue: int) -> str:
+    """Set foreground using 24bit color mode"""
     return f"\e[38;2;{red};{green};{blue}m"
 
 
 def bg_24bit(red: int, green: int, blue: int) -> str:
+    """Set background using 24bit color mode"""
     return f"\e[48;2;{red};{green};{blue}m"
 
 
@@ -1756,10 +1774,20 @@ def fg(
     force_216color are passed (respectively).  Otherwise the code will
     do what it thinks best.
 
+    Args:
+        name: the name of the color to set
+        red: the color to set's red component value
+        green: the color to set's green component value
+        blue: the color to set's blue component value
+        force_16color: force fg to use 16 color mode
+        force_216color: force fg to use 216 color mode
+
+    Returns:
+        String containing the ANSI escape sequence to set desired foreground
+
     >>> import string_utils as su
     >>> su.to_base64(fg('blue'))
     b'G1szODs1OzIxbQ==\\n'
-
     """
     if name is not None and name == 'reset':
         return '\033[39m'
@@ -1811,6 +1839,15 @@ def pick_contrasting_color(
     contrasting color given the red, green, blue of a background
     color or a color name of the background color.
 
+    Args:
+        name: the name of the color to contrast
+        red: the color to contrast's red component value
+        green: the color to contrast's green component value
+        blue: the color to contrast's blue component value
+
+    Returns:
+        An RGB tuple containing a contrasting color
+
     >>> pick_contrasting_color(None, 20, 20, 20)
     (255, 255, 255)
 
@@ -1830,6 +1867,7 @@ def pick_contrasting_color(
 
 
 def guess_name(name: str) -> str:
+    """Try to guess what color the user is talking about"""
     best_guess = None
     max_ratio = None
     for possibility in COLOR_NAMES_TO_RGB:
@@ -1855,10 +1893,17 @@ def bg(
     """Returns an ANSI color code for changing the current background
     color.
 
+    Args:
+        name: the name of the color to set
+        red: the color to set's red component value
+        green: the color to set's green component value
+        blue: the color to set's blue component value
+        force_16color: force bg to use 16 color mode
+        force_216color: force bg to use 216 color mode
+
     >>> import string_utils as su
     >>> su.to_base64(bg("red"))    # b'\x1b[48;5;196m'
     b'G1s0ODs1OzE5Nm0=\\n'
-
     """
     if name is not None and name == 'reset':
         return '\033[49m'