Improve various docstrings.

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.

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

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

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

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

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)