--- a/pydertron.py	Thu Sep 10 14:36:17 2009 -0700
+++ b/pydertron.py	Thu Sep 10 14:55:24 2009 -0700
@@ -1,3 +1,8 @@
+"""
+    Pydertron is a high-level wrapper for Pydermonkey that provides convenient,
+    secure object wrapping between JS and Python space.
+"""
+
 import sys
 import threading
 import traceback
@@ -70,7 +75,12 @@
 
 class SafeJsObjectWrapper(object):
     """
-    Securely wraps a JS object to behave like any normal Python object.
+    Securely wraps a JS object to behave like any normal Python
+    object. Like JS objects, though, accessing undefined object
+    results merely in pydermonkey.undefined.
+
+    Object properties may be accessed either via attribute or
+    item-based lookup.
     """
 
     __slots__ = ['_jsobject', '_sandbox', '_this']
@@ -259,6 +269,12 @@
         self.root = self.wrap_jsobject(root, root)
 
     def set_globals(self, **globals):
+        """
+        Sets the global properties for the root object and all global
+        scopes (e.g., SecurableModules).  This should be called before
+        any scripts are executed.
+        """
+
         self.__globals.update(globals)
         self._install_globals(self.root)
 
@@ -438,18 +454,33 @@
             return jsvalue
 
     def new_array(self, *contents):
+        """
+        Creates a new JavaScript array with the given contents and
+        returns a wrapper for it.
+        """
+
         array = self.wrap_jsobject(self.cx.new_array_object())
         for item in contents:
             array.push(item)
         return array
 
     def new_object(self, **contents):
+        """
+        Creates a new JavaScript object with the given properties and
+        returns a wrapper for it.
+        """
+
         obj = self.wrap_jsobject(self.cx.new_object())
         for name in contents:
             obj[name] = contents[name]
         return obj
 
     def get_calling_script(self):
+        """
+        Returns the filename of the current stack's most recent
+        JavaScript caller.
+        """
+
         frame = self.cx.get_stack()['caller']
         curr_script = None
         while frame and curr_script is None:
@@ -470,6 +501,13 @@
 
     @jsexposed(name='require')
     def _require(self, path):
+        """
+        Implementation for the global require() function, implemented
+        as per the CommonJS SecurableModule specification:
+
+        http://wiki.commonjs.org/wiki/CommonJS/Modules/SecurableModules
+        """
+
         filename = self.fs.find_module(self.get_calling_script(), path)
         if not filename:
             raise pydermonkey.error('Module not found: %s' % path)
@@ -512,6 +550,10 @@
         return retval
 
 class HttpFileSystem(object):
+    """
+    File system through which all resources are loaded over HTTP.
+    """
+
     def __init__(self, base_url):
         self.base_url = base_url
 
@@ -533,7 +575,12 @@
 
         return urllib.urlopen(url)
 
-class SandboxedFileSystem(object):
+class LocalFileSystem(object):
+    """
+    File system through which all resources are loaded over the local
+    filesystem.
+    """
+
     def __init__(self, root_dir):
         self.root_dir = root_dir
 

--- a/test_pydertron.py	Thu Sep 10 14:36:17 2009 -0700
+++ b/test_pydertron.py	Thu Sep 10 14:55:24 2009 -0700
@@ -1,9 +1,13 @@
+"""
+    CommonJS SecurableModule standard compliance tests for Pydertron.
+"""
+
 import os
 import sys
 
 import pydermonkey
 from pydertron import JsSandbox, jsexposed
-from pydertron import SandboxedFileSystem, HttpFileSystem
+from pydertron import LocalFileSystem, HttpFileSystem
 
 def run_test(name, fs):
     sandbox = JsSandbox(fs)
@@ -61,7 +65,7 @@
         dirs = [(os.path.join(base_libpath, name), name)
                 for name in os.listdir(base_libpath)
                 if name not in ['.svn', 'ORACLE']]
-        fsfactory = SandboxedFileSystem
+        fsfactory = LocalFileSystem
 
     totals = {'pass': 0, 'fail': 0}