# HG changeset patch
# User Atul Varma <varmaa@toolness.com>
# Date 1252365958 25200
# Node ID 35ab0ad3c294addac5e7c9736cf9dd271364e078
# Parent  9413bebf2ee616888d53dc8c5bb8e5d2afab4808
Added more docs.

diff -r 9413bebf2ee6 -r 35ab0ad3c294 pydershell/pydershell.py
--- a/pydershell/pydershell.py	Mon Sep 07 16:18:34 2009 -0700
+++ b/pydershell/pydershell.py	Mon Sep 07 16:25:58 2009 -0700
@@ -13,6 +13,8 @@
     at a regular interval.
     """
 
+    # Default interval, in seconds, that the operation callbacks are
+    # triggered at.
     DEFAULT_INTERVAL = 0.25
 
     def __init__(self, interval=DEFAULT_INTERVAL):
@@ -226,6 +228,13 @@
         self.root = self.wrap_jsobject(root, root)
 
     def finish(self):
+        """
+        Cleans up all resources used by the sandbox, breaking any reference
+        cycles created due to issue #2 in pydermonkey:
+
+        http://code.google.com/p/pydermonkey/issues/detail?id=2
+        """
+
         for jsobj in self.__py_to_js.values():
             self.cx.clear_object_private(jsobj)
         del self.__py_to_js
@@ -313,6 +322,13 @@
         return self.cx.new_object(value, self.__type_protos[pyproto])
 
     def wrap_pyobject(self, value):
+        """
+        Wraps the given Python object for export to untrusted JS.
+
+        If the Python object isn't of a type that can be exposed to JS,
+        a TypeError is raised.
+        """
+
         if (isinstance(value, (int, basestring, float, bool)) or
             value is pydermonkey.undefined or
             value is None):
@@ -329,6 +345,12 @@
                             type(value).__name__)
 
     def wrap_jsobject(self, jsvalue, this=None):
+        """
+        Wraps the given pydermonkey.Object for import to trusted
+        Python code. If the type is just a primitive, it's simply
+        returned, since no wrapping is needed.
+        """
+
         if this is None:
             this = self.root.wrapped_jsobject
         if isinstance(jsvalue, pydermonkey.Function):
@@ -351,6 +373,10 @@
             return jsvalue
 
     def run_script(self, filename):
+        """
+        Runs the given JS script, returning 0 on success, -1 on failure.
+        """
+
         retval = -1
         contents = open(filename).read()
         cx = self.cx