More docs...

joy/vui/main.py

@@ -17,6 +17,14 @@
 #    You should have received a copy of the GNU General Public License
 #    along with Thun.  If not see <http://www.gnu.org/licenses/>.
 #
+'''
+
+Main Module
+======================================
+
+Pulls everything together.
+
+'''
 import os, sys, traceback
 import pygame
 from joy.library import initialize, DefinitionWrapper, SimpleFunctionWrapper
@@ -34,6 +42,7 @@ if JOY_HOME is None:
 
 
 def load_definitions(pt, dictionary):
+    '''Load definitions from ``definitions.txt``.'''
     lines = pt.open('definitions.txt')[1]
     for line in lines:
         if '==' in line:
@@ -41,12 +50,23 @@ def load_definitions(pt, dictionary):
 
 
 def load_primitives(home, name_space):
+    '''Load primitives from ``library.py``.'''
     fn = os.path.join(home, 'library.py')
     if os.path.exists(fn):
         execfile(fn, name_space)
 
 
 def init():
+    '''
+    Initialize the system.
+    
+    * Init PyGame
+    * Create main window
+    * Start the PyGame clock
+    * Set the event mask
+    * Create the PersistTask
+
+    '''
     print 'Initializing Pygame...'
     pygame.init()
     print 'Creating window...'
@@ -62,6 +82,18 @@ def init():
 
 
 def init_context(screen, clock, pt):
+    '''
+    More initialization
+
+    * Create the Joy dictionary
+    * Create the Display
+    * Open the log, menu, and scratch text viewers, and the stack pickle
+    * Start the main loop
+    * Create the World object
+    * Register PersistTask and World message handlers with the Display
+    * Load user function definitions.
+
+    '''
     D = initialize()
     d = display.Display(
         screen,
@@ -82,6 +114,10 @@ def init_context(screen, clock, pt):
 
 
 def error_guard(loop, n=10):
+    '''
+    Run a loop function, retry for ``n`` exceptions.
+    Prints tracebacks on ``sys.stderr``.
+    '''
     error_count = 0
     while error_count < n:
         try:
@@ -93,11 +129,13 @@ def error_guard(loop, n=10):
 
 
 class FileFaker(object):
+    '''Pretends to be a file object but writes to log instead.'''
 
     def __init__(self, log):
         self.log = log
 
     def write(self, text):
+        '''Write text to log.'''
         self.log.append(text)
 
     def flush(self):
@@ -105,6 +143,15 @@ class FileFaker(object):
 
 
 def main(screen, clock, pt):
+    '''
+    Main function.
+
+    * Call ``init_context()``
+    * Load primitives
+    * Create an ``evaluate`` function that lets you just eval some Python code
+    * Redirect ``stdout`` to the log using a ``FileFaker`` object, and...
+    * Start the main loop.
+    '''
     name_space = init_context(screen, clock, pt)
     load_primitives(pt.home, name_space.copy())