From 98ee6e82c63d98cc8022e271e6e4336c73b4b3f4 Mon Sep 17 00:00:00 2001
From: Ethan Dalool <git@voussoir.net>
Date: Sun, 22 Aug 2021 20:46:12 -0700
Subject: [PATCH] Improve various docstrings.

---
 voussoirkit/bencode.py         |  9 +++++++++
 voussoirkit/betterhelp.py      | 24 +++++++++++++-----------
 voussoirkit/expressionmatch.py | 12 ++++++++----
 voussoirkit/hms.py             |  2 +-
 voussoirkit/imagetools.py      |  5 +++++
 voussoirkit/stringtools.py     |  9 ++++++---
 6 files changed, 42 insertions(+), 19 deletions(-)

diff --git a/voussoirkit/bencode.py b/voussoirkit/bencode.py
index 4f8b6b8..38ff3d0 100644
--- a/voussoirkit/bencode.py
+++ b/voussoirkit/bencode.py
@@ -1,3 +1,12 @@
+'''
+bencode
+=======
+
+This module provides the functions bencode and bdecode for working with
+Bencode data.
+
+https://en.wikipedia.org/wiki/Bencode
+'''
 def bencode(data):
     '''
     Encode python types to bencode.
diff --git a/voussoirkit/betterhelp.py b/voussoirkit/betterhelp.py
index 6aaa28c..f1c10fd 100644
--- a/voussoirkit/betterhelp.py
+++ b/voussoirkit/betterhelp.py
@@ -42,18 +42,20 @@ def can_use_bare_subparsers(subparser_action):
 def docstring_preview(text):
     '''
     This function assumes that your docstring is formatted with a single blank
-    line separating the command's primary summary and the rest of the text.
-    For example:
+    line separating the command's primary summary and the rest of the text,
+    and will return the summary above the blank.
 
-        cookbacon = """
-        cookbacon: Cooks all nearby bacon to a specified temperature.
-
-        Usage:
-            > cookbacon 350F
-            > cookbacon 175C
-        """
-
-    and will return the first portion.
+    >>> cookbacon = """
+    ... cookbacon: Cooks all nearby bacon to a specified temperature.
+    ...
+    ... Usage:
+    ...     > cookbacon 350F
+    ...     > cookbacon 175C
+    ... """
+    >>>
+    >>>
+    >>> docstring_preview(cookbacon)
+    'cookbacon: Cooks all nearby bacon to a specified temperature.'
     '''
     text = text.split('\n\n')[0].strip()
     return text
diff --git a/voussoirkit/expressionmatch.py b/voussoirkit/expressionmatch.py
index 41ed3f6..c106a0f 100644
--- a/voussoirkit/expressionmatch.py
+++ b/voussoirkit/expressionmatch.py
@@ -3,10 +3,14 @@ This module provides the ExpressionTree class, which parses a query expression
 like "a AND (b OR c)" and then evaluates whether an input satisfies the query.
 
 Basic usage:
-tree = expressionmatch.ExpressionTree.parse('a AND (b OR c)')
-tree.evaluate('a b')
-tree.evaluate('a c')
-tree.evaluate('b c')
+>>> tree = ExpressionTree.parse('a AND (b OR c)')
+>>> tree.evaluate('a b')
+True
+>>> tree.evaluate('a c')
+True
+>>> tree.evaluate('b c')
+False
+>>>
 
 The available operators are:
 a AND b
diff --git a/voussoirkit/hms.py b/voussoirkit/hms.py
index 13bbd4c..3147541 100644
--- a/voussoirkit/hms.py
+++ b/voussoirkit/hms.py
@@ -5,7 +5,7 @@ from voussoirkit import pipeable
 
 def hms_to_seconds(hms):
     '''
-    Convert hh:mm:ss string to an integer seconds.
+    Convert hh:mm:ss string to an integer or float of seconds.
     '''
     parts = hms.split(':')
     seconds = 0
diff --git a/voussoirkit/imagetools.py b/voussoirkit/imagetools.py
index 50f8c7b..bbb1f49 100644
--- a/voussoirkit/imagetools.py
+++ b/voussoirkit/imagetools.py
@@ -54,6 +54,11 @@ def rotate_by_exif(image):
 
     Returns (image, exif) where exif has the orientation key set to 1,
     the upright position, if the rotation was successful.
+
+    You should be able to call image.save('filename.jpg', exif=exif) with
+    these returned values.
+    (To my knowledge, I can not put the exif back into the Image object itself.
+    There is getexif but no setexif or putexif, etc.)
     '''
     # Thank you Scabbiaza
     # https://stackoverflow.com/a/26928142
diff --git a/voussoirkit/stringtools.py b/voussoirkit/stringtools.py
index 1f400c3..bc76ff3 100644
--- a/voussoirkit/stringtools.py
+++ b/voussoirkit/stringtools.py
@@ -13,7 +13,8 @@ def comma_space_split(text):
     Split the string by commas and spaces, discarding all extra
     whitespace and blank parts.
 
-    'a b, c,,d' -> ['a', 'b', 'c', 'd']
+    >>> comma_space_split('a b, c,,d')
+    ['a', 'b', 'c', 'd']
     '''
     if text is None:
         return text
@@ -49,8 +50,10 @@ def natural_sorter(s):
 
 def pascal_to_loudsnakes(text):
     '''
-    PascalCase -> PASCAL_CASE
-    HTMLDocument -> HTML_DOCUMENT
+    >>> pascal_to_loudsnakes('PascalCase')
+    'PASCAL_CASE'
+    >>> pascal_to_loudsnakes('HTMLDocument')
+    'HTML_DOCUMENT'
     '''
     text = re.sub(r'([a-z])([A-Z])', r'\1_\2', text)
     text = re.sub(r'([A-Z]+)([A-Z][a-z])', r'\1_\2', text)