Documentation tweaks.

README.md

@@ -66,7 +66,6 @@ To set up the examples first run:
 
 Then check out the example html files.
 
-
 ## Building library
 
 For wax users, a minified library is already provided in build/.

control/lib/melt.js

@@ -1,4 +1,14 @@
-// TODO: rewrite without underscore
+// Like underscore's bind, except it runs a function
+// with no arguments off of an object.
+//
+//     var map = ...;
+//     w(map).melt(myFunction);
+//
+// is equivalent to
+//
+//     var map = ...;
+//     myFunction(map);
+//
 var w = function(self) {
     self.melt = function(func, obj) {
         func.apply(obj, [self, obj]);

control/lib/util.js

@@ -1,9 +1,11 @@
 wax.util = wax.util || {};
 
-
+// Utils are extracted from other libraries or
+// written from scratch to plug holes in browser compatibility.
 wax.util = {
     // From Bonzo
     offset: function(el) {
+        // TODO: window margin offset
         var width = el.offsetWidth;
         var height = el.offsetHeight;
         var top = el.offsetTop;
@@ -22,6 +24,8 @@ wax.util = {
         };
     },
     // From underscore, minus funcbind for now.
+    // Returns a version of a function that always has the second parameter,
+    // `obj`, as `this`.
     bind: function(func, obj) {
       var args = Array.prototype.slice.call(arguments, 2);
       return function() {
@@ -32,7 +36,7 @@ wax.util = {
     isString: function(obj) {
       return !!(obj === '' || (obj && obj.charCodeAt && obj.substr));
     },
-
+    // IE doesn't have indexOf
     indexOf: function(array, item) {
       var nativeIndexOf = Array.prototype.indexOf;
       if (array === null) return -1;
@@ -41,20 +45,20 @@ wax.util = {
       for (i = 0, l = array.length; i < l; i++) if (array[i] === item) return i;
       return -1;
     },
-
+    // is this object an array?
     isArray: Array.isArray || function(obj) {
       return Object.prototype.toString.call(obj) === '[object Array]';
     },
-
+    // From underscore: reimplement the ECMA5 `Object.keys()` methodb
     keys: Object.keys || function(obj) {
       var hasOwnProperty = Object.prototype.hasOwnProperty;
       if (obj !== Object(obj)) throw new TypeError('Invalid object');
       var keys = [];
       for (var key in obj) if (hasOwnProperty.call(obj, key)) keys[keys.length] = key;
       return keys;
     },
-
-    // From quirksmode
+    // From quirksmode: normalize the offset of an event from the top-left
+    // of the page.
     eventoffset: function(e) {
         var posx = 0;
         var posy = 0;

control/mm/hash.js

@@ -40,8 +40,10 @@ var locationHash = {
 };
 
 wax.hash = function(map, options) {
-    var s0, // cached location.hash
-        lat = 90 - 1e-8, // allowable latitude range
+    // cached location.hash
+    var s0,
+        // allowable latitude range
+        lat = 90 - 1e-8,
         map;
 
     var hash = {
@@ -53,7 +55,8 @@ wax.hash = function(map, options) {
                 args[i] = Number(args);
             }
             if (args.length < 3) {
-                return true; // replace bogus hash
+                // replace bogus hash
+                return true;
             } else if (args.length == 3) {
                 map.setCenterZoom(new com.modestmaps.Location(args[1], args[2]), args[0]);
             }
@@ -65,6 +68,8 @@ wax.hash = function(map, options) {
             map.addCallback('drawn', throttle(hash.move, 500));
             options.manager.stateChange(hash.stateChange);
         },
+        // Currently misnamed. Get the hash string that will go in the URL,
+        // pulling from the map object
         formatter: function() {
             var center = map.getCenter(),
                 zoom = map.getZoom(),
@@ -77,13 +82,16 @@ wax.hash = function(map, options) {
             var s1 = hash.formatter();
             if (s0 !== s1) {
                 s0 = s1;
-                options.manager.pushState(s0); // don't recenter the map!
+                // don't recenter the map!
+                options.manager.pushState(s0);
             }
         },
         stateChange: function(state) {
-            if (state === s0) return; // ignore spurious hashchange events
+            // ignore spurious hashchange events
+            if (state === s0) return;
             if (hash.parser((s0 = state).substring(1))) {
-              hash.move(); // replace bogus hash
+              // replace bogus hash
+              hash.move();
             }
         },
         // If a state isn't present when you initially load the map, the map should