formatting: document exceptions & return types consistently

sopel/formatting.py

@@ -125,6 +125,7 @@
 
 
 class colors(str, Enum):
+    """Mapping of color names to mIRC code values."""
     # Mostly aligned with https://modern.ircdocs.horse/formatting.html#colors
     # which are likely based on mIRC's color names (https://www.mirc.com/colors.html)
     WHITE = '00'
@@ -188,6 +189,9 @@ def color(text, fg=None, bg=None):
     :param str text: the text to format
     :param mixed fg: the foreground color
     :param mixed bg: the background color
+    :raises TypeError: if ``text`` is not a string
+    :raises ValueError: if ``fg`` or ``bg`` is an unrecognized color value)
+    :rtype: str
 
     The color can be a string of the color name, or an integer in the range
     0-99. The known color names can be found in the :class:`colors` class of
@@ -231,14 +235,17 @@ def hex_color(text, fg=None, bg=None):
     :param str text: the text to format
     :param str fg: the foreground color
     :param str bg: the background color
+    :raises TypeError: if ``text`` is not a string
+    :raises ValueError: if ``fg`` or ``bg`` is an unrecognized color value)
+    :rtype: str
 
     The color can be provided with a string of either 3 or 6 hexadecimal digits.
     As in CSS, 3-digit colors will be interpreted as if they were 6-digit colors
     with each digit repeated (e.g. color ``c90`` is identical to ``cc9900``). Do
     not include the leading ``#`` symbol.
 
     .. note::
-        This is a relatively new IRC formatting convention. Use only when you
+        This is a relatively new IRC formatting convention. Use it only when you
         can afford to have its meaning lost, as not many clients support it yet.
     """
     if not fg and not bg:
@@ -258,6 +265,8 @@ def bold(text):
     """Return the text, with bold IRC formatting.
 
     :param str text: the text to format
+    :raises TypeError: if ``text`` is not a string
+    :rtype: str
     """
     return ''.join([CONTROL_BOLD, text, CONTROL_BOLD])
 
@@ -266,6 +275,8 @@ def italic(text):
     """Return the text, with italic IRC formatting.
 
     :param str text: the text to format
+    :raises TypeError: if ``text`` is not a string
+    :rtype: str
     """
     return ''.join([CONTROL_ITALIC, text, CONTROL_ITALIC])
 
@@ -274,6 +285,8 @@ def underline(text):
     """Return the text, with underline IRC formatting.
 
     :param str text: the text to format
+    :raises TypeError: if ``text`` is not a string
+    :rtype: str
     """
     return ''.join([CONTROL_UNDERLINE, text, CONTROL_UNDERLINE])
 
@@ -282,9 +295,11 @@ def strikethrough(text):
     """Return the text, with strikethrough IRC formatting.
 
     :param str text: the text to format
+    :raises TypeError: if ``text`` is not a string
+    :rtype: str
 
     .. note::
-        This is a relatively new IRC formatting convention. Use only when you
+        This is a relatively new IRC formatting convention. Use it only when you
         can afford to have its meaning lost, as not many clients support it yet.
     """
     return ''.join([CONTROL_STRIKETHROUGH, text, CONTROL_STRIKETHROUGH])
@@ -294,9 +309,11 @@ def monospace(text):
     """Return the text, with monospace IRC formatting.
 
     :param str text: the text to format
+    :raises TypeError: if ``text`` is not a string
+    :rtype: str
 
     .. note::
-        This is a relatively new IRC formatting convention. Use only when you
+        This is a relatively new IRC formatting convention. Use it only when you
         can afford to have its meaning lost, as not many clients support it yet.
     """
     return ''.join([CONTROL_MONOSPACE, text, CONTROL_MONOSPACE])
@@ -306,6 +323,8 @@ def reverse(text):
     """Return the text, with reverse-color IRC formatting.
 
     :param str text: the text to format
+    :raises TypeError: if ``text`` is not a string
+    :rtype: str
 
     .. note::
         This code isn't super well supported, and its behavior even in clients
@@ -318,6 +337,7 @@ def plain(text):
     """Return the text without any IRC formatting.
 
     :param str text: text with potential IRC formatting control code(s)
+    :raises TypeError: if ``text`` is not a string
     :rtype: str
     """
     if '\x03' in text or '\x04' in text: