--- a/js/browser-couch.js	Wed Apr 15 08:48:45 2009 -0700
+++ b/js/browser-couch.js	Wed Apr 15 09:10:37 2009 -0700
@@ -34,15 +34,27 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
+// = BrowserCouch =
+//
+// This is the primary implementation file for BrowserCouch.
+
+// === {{{isArray()}}} ===
+//
+// A helper function to determine whether an object is an Array
+// or not. Taken from "Remedial Javascript" by Douglas Crockford
+// at http://javascript.crockford.com/remedial.html.
+
 function isArray(value) {
-  // Taken from "Remedial Javascript" by Douglas Crockford:
-  // http://javascript.crockford.com/remedial.html
-
   return (typeof value.length === 'number' &&
           !(value.propertyIsEnumerable('length')) &&
           typeof value.splice === 'function');
 }
 
+// === {{{ModuleLoader}}} ===
+//
+// A really basic module loader that allows dependencies to be
+// "lazy-loaded" when their functionality is needed.
+
 var ModuleLoader = {
   LIBS: {JSON: "js/ext/json2.js"},
 
@@ -93,6 +105,22 @@
   }
 };
 
+// == MapReducers ==
+//
+// //MapReducer// is a generic interface for any map-reduce
+// implementation. Any object implementing this interface will need
+// to be able to work asynchronously, passing back control to the
+// client at a given interval, so that the client has the ability to
+// pause/cancel or report progress on the calculation if needed.
+
+// === {{{WebWorkerMapReducer}}} ===
+//
+// A MapReducer that uses
+// [[https://developer.mozilla.org/En/Using_DOM_workers|Web Workers]]
+// for its implementation, allowing the client to take advantage of
+// multiple processor cores and potentially decouple the map-reduce
+// calculation from the user interface.
+
 function WebWorkerMapReducer(numWorkers, Worker) {
   if (!Worker)
     Worker = window.Worker;
@@ -179,9 +207,15 @@
       nextJob(pool[i]);
   };
 
+  // TODO: Actually implement our own reduce() method here instead
+  // of delegating to the single-threaded version.
   this.reduce = SingleThreadedMapReducer.reduce;
 };
 
+// === {{{SingleThreadedMapReducer}}} ===
+//
+// A MapReducer that works on the current thread.
+
 var SingleThreadedMapReducer = {
   map: function STMR_map(map, dict, progress,
                          chunkSize, finished) {
@@ -260,6 +294,17 @@
   }
 };
 
+// == Storage ==
+//
+// //Storage// is a generic interface for a persistent storage
+// implementation capable of storing JSON-able objects.
+
+// === {{{FakeStorage}}} ===
+//
+// This Storage implementation isn't actually persistent; it's just
+// a placeholder that can be used for testing purposes, or when no
+// persistent storage mechanisms are available.
+
 function FakeStorage() {
   var db = {};
 
@@ -300,6 +345,11 @@
   };
 };
 
+// === {{{LocalStorage}}} ===
+//
+// This Storage implementation uses the browser's HTML5 support for
+// {{{localStorage}}} or {{{globalStorage}}} for object persistence.
+
 function LocalStorage(JSON) {
   var storage;
 
@@ -344,6 +394,11 @@
   };
 }
 
+// == BrowserCouch ==
+//
+// {{{BrowserCouch}}} is the main object that clients will use.  It's
+// intended to be somewhat analogous to CouchDB's RESTful API.
+
 var BrowserCouch = {
   get: function BC_get(name, cb, storage) {
     if (!storage)