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/_ttbp.py

@@ -81,6 +81,12 @@ SUBJECTS = ["help request", "bug report", "feature suggestion", "general comment
 ##
 
 def redraw(leftover=""):
+    '''
+    screen clearing
+
+    * clears the screen and reprints the banner, plus whatever leftover text to be hilights
+    '''
+
     os.system("clear")
     print(BANNER)
     print(SPACER)
@@ -88,9 +94,16 @@ def redraw(leftover=""):
         print("> "+leftover+"\n")
 
 def start():
+    '''
+    main engine head
+
+    * called on program start
+    * calls config check
+    * proceeds to main menu
+    * handles ^c and ^d ejects
+    '''
+
     redraw()
-    #print(chatter.say("greet")+", "+chatter.say("friend"))
-    #print("(remember, you can always press ctrl-c to come home)\n")
     print("""
 if you don't want to be here at any point, press <ctrl-d> and it'll all go away.
 just keep in mind that you might lose anything you've started here.\
@@ -117,13 +130,29 @@ just keep in mind that you might lose anything you've started here.\
             break
 
 def stop():
+    '''
+    closer
+
+    * prints ending text
+    '''
+
     return "\n\n\t"+chatter.say("bye")+"\n\n"
 
 def check_init():
+    '''
+    user handler
+
+    * checks for presence of ttbprc
+    * checks for last run version
+    '''
+
     global SETTINGS
+
     print("\n\n")
     if os.path.exists(os.path.join(os.path.expanduser("~"),".ttbp")):
         print(chatter.say("greet")+", "+USER+".\n")
+
+        ## ttbprc validation
         while not os.path.isfile(TTBPRC):
             setup_handler()
         try:
@@ -135,6 +164,7 @@ def check_init():
         if not updated():
             print(update_version())
 
+        ## when ready, enter main program and load core engine
         raw_input("press <enter> to explore your feels.\n\n")
         core.load()
 
@@ -143,32 +173,45 @@ def check_init():
         return init()
 
 def init():
+    '''
+    new user creation
+
+    * introduces user
+    * calls setup functinos
+    '''
+
     try:
         raw_input("""
 i don't recognize you, stranger. let's make friends.
 
-press <enter> to begin, or <ctrl-c> to get out of here.
+press <enter> to begin, or <ctrl-c> to get out of here.\
         """)
     except KeyboardInterrupt:
         print("\n\nthanks for checking in! i'll always be here.\n\n")
         quit()
 
+    ## record user in source list
     users = open(USERFILE, 'a')
     users.write(USER+"\n")
     users.close()
+
+    ## make .ttbp directory structure
     subprocess.call(["mkdir", PATH])
     subprocess.call(["mkdir", CONFIG])
     subprocess.call(["mkdir", DATA])
 
+    ## create header file
     header = gen_header()
     headerfile = open(os.path.join(CONFIG, "header.txt"), 'w')
     for line in header:
         headerfile.write(line)
     headerfile.close()
 
+    ## copy footer and default stylesheet
     subprocess.call(["cp", os.path.join(SOURCE, "config", "defaults", "footer.txt"), CONFIG])
     subprocess.call(["cp", os.path.join(SOURCE, "config", "defaults", "style.css"), CONFIG])
 
+    ## run user-interactive setup and load core engine
     setup()
     core.load()
 
@@ -176,10 +219,17 @@ press <enter> to begin, or <ctrl-c> to get out of here.
     return ""
 
 def gen_header():
-    header ="""
+    '''
+    header generator
+
+    builds header to insert username
+    '''
+
+    header ="""\
 <!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 3.2//EN\">
 <html>
     <head>
+        <!--- this header automatically generated by ttbp initialization on """+time.strftime("%Y-%m-%d %h:m")+""" --->
         <title>~"""+USER+""" on TTBP</title>
         <link rel=\"stylesheet\" href=\"style.css\" />
     </head>
@@ -198,6 +248,13 @@ def gen_header():
     return header
 
 def setup_handler():
+    '''
+    setup wrapper function
+
+    * calls setup()
+    * handles ^c
+    '''
+
     print("\nyour ttbp configuration doesn't look right. let's make you a fresh copy.\n\n")
     try:
         setup()
@@ -206,6 +263,17 @@ def setup_handler():
         setup()
 
 def setup():
+    '''
+    master setup function
+
+    * editor selection
+    * publishing toggle
+    * publish/unpublish as needed
+    * directory selection
+
+    TODO: break this out better?
+    '''
+
     global SETTINGS
 
     # editor selection
@@ -219,6 +287,7 @@ def setup():
 
     if publishing():
         print("publish directory: ~"+USER+"/public_html/"+SETTINGS.get("publish dir"))
+
     # save settings
     ttbprc = open(TTBPRC, "w")
     ttbprc.write(json.dumps(SETTINGS, sort_keys=True, indent=2, separators=(',',':')))
@@ -231,6 +300,12 @@ def setup():
 ## menus
 
 def print_menu(menu):
+    '''
+    pretty menu handler
+
+    * takes list of options and prints them
+    '''
+
     i = 0
     for x in menu:
         line = []
@@ -244,6 +319,10 @@ def print_menu(menu):
         i += 1
 
 def main_menu():
+    '''
+    main navigation menu
+    '''
+
     menuOptions = [
             "record your feels",
             "review your feels",
@@ -252,8 +331,8 @@ def main_menu():
             "change your settings",
             "send some feedback",
             "see credits"]
+
     print("you're at ttbp home. remember, you can always press <ctrl-c> to come back here.\n\n")
-    #print("you're at ttbp home.\n\n")
     print_menu(menuOptions)
 
     try:
@@ -301,9 +380,14 @@ def main_menu():
 
     return main_menu()
 
-###
-
 def feedback_menu():
+    '''
+    feedback handling menu
+
+    * selects feedback type
+    * calls feedback writing function
+    '''
+
     print("you're about to send mail to ~endorphant about ttbp\n\n")
 
     print_menu(SUBJECTS)
@@ -443,7 +527,7 @@ press <enter> to begin recording your feels.
 
     return
 
-def send_feedback(entered, subject="none", mailbox=os.path.join(FEEDBACK, USER+"-"+time.strftime("%Y%m%d-%H%M")+".msg")):
+def send_feedback(entered, subject="none"):
 
     message = ""
 
@@ -817,5 +901,6 @@ def update_version():
 
 #####
 
+if __name__ == '__main__':
     start()
 #print("ttbp beta is out to lunch. bbl.")

bin/ttbp.py

@@ -27,7 +27,6 @@ the complete codebase is available at:
 https://github.com/modgethanc/ttbp
 '''
 
-import os
 import os
 import random
 import tempfile

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

changelog.txt

@@ -17,10 +17,12 @@ TO-DO:
 	(flair)
 
 	-graffiti wall
-	-command line flags:
+	-command line flags
-		(maybe; not sure i want this to be a feature at all)
+		*maybe; not sure i want this to be a feature at all
 		-shortcut to most recent feels, writing entry, seeing own entry
 	-#hashtags
+	-rainbow menu selection
+	-break out hardcoded globals into config files
 
 ------