--- a/spidermonkey-playground.cpp	Mon Jun 22 08:33:34 2009 -0700
+++ b/spidermonkey-playground.cpp	Mon Jun 22 08:52:17 2009 -0700
@@ -34,6 +34,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+// This file is based on the code in the JSAPI User Guide:
+//
+// https://developer.mozilla.org/En/SpiderMonkey/JSAPI_User_Guide
+
 #include "string.h"
 #include "jsapi.h"
 #include "jsdbgapi.h"
@@ -57,6 +61,8 @@
   JSCLASS_NO_OPTIONAL_MEMBERS
 };
 
+// This native JS function prints the given string to the console.
+
 static JSBool print(JSContext *cx, JSObject *obj, uintN argc, jsval *argv,
                     jsval *rval)
 {
@@ -70,6 +76,17 @@
   return JS_TRUE;
 }
 
+// This native JS function is an implementation of the SecurableModule
+// require() function.  For more information, see:
+//
+// https://wiki.mozilla.org/ServerJS/Modules/SecurableModules
+//
+// The function takes two parameters: a filename to import, and a JS
+// object containing objects to export into the module.  The latter is
+// accessible from the loaded module via a global called 'imports'.
+//
+// This function returns the SecurableModule's 'exports' global.
+
 static JSBool require(JSContext *cx, JSObject *obj, uintN argc, jsval *argv,
                       jsval *rval)
 {
@@ -115,6 +132,9 @@
   return JS_TRUE;
 }
 
+// This native JS function looks up the property of an object, bypassing
+// security checks and getters/setters.
+
 static JSBool lookupProperty(JSContext *cx, JSObject *obj, uintN argc,
                              jsval *argv, jsval *rval)
 {
@@ -131,6 +151,9 @@
   return JS_LookupPropertyById(cx, target, argv[1], rval);
 }
 
+// This native JS function returns a JS object containing metadata about
+// the given function.
+
 static JSBool functionInfo(JSContext *cx, JSObject *obj, uintN argc,
                            jsval *argv, jsval *rval)
 {
@@ -163,6 +186,10 @@
   return JS_TRUE;
 }
 
+// This native JS function returns a JS representation of the current
+// state of the stack, starting with the callee's stack frame and going
+// up from there.
+
 static JSBool stack(JSContext *cx, JSObject *obj, uintN argc, jsval *argv,
                     jsval *rval)
 {
@@ -245,6 +272,11 @@
   return JS_TRUE;
 }
 
+// Our global hook called whenever an exception is thrown saves the current
+// exception and stack information to the 'lastException' and
+// 'lastExceptionTraceback' globals of the TCB, respectively, much like
+// Python's sys.exc_info().
+
 static JSTrapStatus throwHook(JSContext *cx, JSScript *script, jsbytecode *pc,
                               jsval *rval, void *closure)
 {
@@ -278,6 +310,10 @@
   return JSTRAP_CONTINUE;
 }
 
+// Our global checkAccess callback just checks to see if a JS function called
+// 'checkAccess' has been defined in the TCB, and delegates to that if so. If
+// not, though, we do a default checkAccess.
+
 static JSBool checkAccess(JSContext *cx, JSObject *obj, jsval id,
                           JSAccessMode mode, jsval *vp)
 {
@@ -293,6 +329,8 @@
                                 vp);
   }
 
+  // TODO: This doesn't work for the 'caller' attribute, and possibly other
+  // things too.
   return JS_LookupPropertyById(cx, obj, id, vp);
 }