more documentation updates

holy crap! here i am, about a decade and a half after my first Formal
Instruction in programming, and i suddenly understand code
documentation. part of this is that sometimes i stare at functions
forgetting why they're there, or start writing a function with the
distinct feeling that i'm typing code i've already typed before, and
realize that maybe there's a better way.

so i skimmed code from other people that i've used in my own repos, and
lifted the general gist of their commenting style while doing things
that feel right to me. i still don't know exactly how i like things, but
i'm learning. this is the best way i learn things.

then. then! i learned that i can just pydoc any of my modules and pydoc
will generate literally the same thing that i read when i pydoc other
module! what. WHAT. this is amazing. i feel like a real person. i
understand where those docs come from now, and how to make them myself.

i'm learning so much.

why does this feel so amazing.

all of this is in a commit message that i'm going to fire off into the
sun but i just need to put this out there because this feels important.

bin/util.py

@@ -33,6 +33,10 @@ lastcolor = colorama.Fore.RESET
 p = inflect.engine()
 
 def set_rainbow():
+    '''
+    prints a random terminal color code
+    '''
+
     global lastcolor
 
     color = lastcolor
@@ -44,9 +48,17 @@ def set_rainbow():
     print(color)
 
 def reset_color():
+    '''
+    prints terminal color code reset
+    '''
+
     print(colorama.Fore.RESET)
 
 def attach_rainbow():
+    '''
+    returns a random terminal color code, presumably to be 'attached' to a string
+    '''
+
     global lastcolor
 
     color = lastcolor
@@ -57,12 +69,28 @@ def attach_rainbow():
     return color
 
 def attach_reset():
+    '''
+    returns terminal color code reset, presumably to be 'attached' to a string
+    '''
+
     return colorama.Style.RESET_ALL
 
 def hilight(text):
+    '''
+    takes a string and highlights it on return
+    '''
+
     return colorama.Style.BRIGHT+text+colorama.Style.NORMAL
 
 def pretty_time(time):
+    '''
+    human-friendly time formatter
+
+    takes an integer number of seconds and returns a phrase that describes it,
+    using the largest possible figure, rounded down (ie, time=604 returns '10
+    minutes', not '10 minutes, 4 seconds' or '604 seconds')
+    '''
+
     m, s = divmod(time, 60)
     if m > 0:
         h, m = divmod(m, 60)
@@ -86,7 +114,9 @@ def pretty_time(time):
         return p.no("second", s)
 
 def genID(digits=5):
-    # makes a string of digits
+    '''
+    returns a string-friendly string of digits, which can start with 0
+    '''
 
     id = ""
     x  = 0