Comment the need for rooted JS_NewScriptObject; whitespace/comment cleanup.

js/src/jsapi.h

@@ -953,6 +953,22 @@ JS_CompileFileHandleForPrincipals(JSContext *cx, JSObject *obj,
                                   const char *filename, FILE *fh,
                                   JSPrincipals *principals);
 
+/*
+ * NB: you must use JS_NewScriptObject and root a pointer to its return value
+ * in order to keep a JSScript and its atoms safe from garbage collection after
+ * creating the script via JS_Compile* and before a JS_ExecuteScript* call.
+ * E.g., and without error checks:
+ *
+ *    JSScript *script = JS_CompileFile(cx, global, filename);
+ *    JSObject *scrobj = JS_NewScriptObject(cx, script);
+ *    JS_AddNamedRoot(cx, &scrobj, "scrobj");
+ *    do {
+ *        jsval result;
+ *        JS_ExecuteScript(cx, global, script, &result);
+ *        JS_GC();
+ *    } while (!JSVAL_IS_BOOLEAN(result) || JSVAL_TO_BOOLEAN(result));
+ *    JS_RemoveRoot(cx, &scrobj);
+ */
 extern JS_PUBLIC_API(JSObject *)
 JS_NewScriptObject(JSContext *cx, JSScript *script);
 

js/src/jscntxt.c

@@ -193,13 +193,13 @@ js_DestroyContext(JSContext *cx, JSGCMode gcmode)
     if (last) {
         /* Always force, so we wait for any racing GC to finish. */
         js_ForceGC(cx);
-	js_FreeAtomState(cx, &rt->atomState);
+        js_FreeAtomState(cx, &rt->atomState);
 
         /* Take the runtime down now that it has no contexts. */
-	JS_LOCK_RUNTIME(rt);
-    	rt->state = JSRTS_DOWN;
-	JS_NOTIFY_ALL_CONDVAR(rt->stateChange);
-	JS_UNLOCK_RUNTIME(rt);
+        JS_LOCK_RUNTIME(rt);
+        rt->state = JSRTS_DOWN;
+        JS_NOTIFY_ALL_CONDVAR(rt->stateChange);
+        JS_UNLOCK_RUNTIME(rt);
     } else {
         if (gcmode == JS_FORCE_GC)
             js_ForceGC(cx);

js/src/jsfile.c

@@ -1685,7 +1685,7 @@ file_readln(JSContext *cx, JSObject *obj, uintN argc, jsval *argv, jsval *rval)
                 endofline = JS_TRUE;
                 goto loop;
             }
-            if (data2!='\n') { /* we read one char to far. buffer it. */
+            if (data2!='\n') { /* We read one char too far.  Buffer it. */
                 file->charBuffer = data2;
                 file->charBufferUsed = JS_TRUE;
             }