Cleaning up the docs to a marginally acceptable level.

lib/OpenLayers/Control/UTFGrid.js

@@ -11,8 +11,32 @@
 
 /**
  * Class: OpenLayers.Control.UTFGrid
- * The UTFGrid control displays .... 
- * pointer, as it is moved about the map.
+ *
+ * This Control provides behavior associated with UTFGrid Layers.
+ * These 'hit grids' provide underlying feature attributes without
+ * calling the server (again). This control allows Mousemove, Hovering 
+ * and Click events to trigger callbacks that use the attributes in 
+ * whatever way you need. 
+ *
+ * The most common example may be a UTFGrid layer containing feature
+ * attributes that are displayed in a div as you mouseover.
+ *
+ * Example Code:
+ *
+ * (start code)
+ * var world_utfgrid = new OpenLayers.Layer.UTFGrid( 
+ *     'UTFGrid Layer', 
+ *     "http://tiles/world_utfgrid/${z}/${x}/${y}.json"
+ * );
+ * map.addLayer(world_utfgrid);
+ * 
+ * var control = new OpenLayers.Control.UTFGrid({
+ *     'div': 'attrsdiv',
+ *     'layers': [world_utfgrid],
+ *     'handlerMode': 'move'
+ * })
+ * (end code)
+ *
  *
  * Inherits from:
  *  - <OpenLayers.Control>
@@ -26,17 +50,28 @@ OpenLayers.Control.UTFGrid = OpenLayers.Class(OpenLayers.Control, {
      */
     autoActivate: true,
 
+    /** 
+     * APIProperty: Layers
+     * List of layers to consider. Must be Layer.UTFGrids
+     * `null` is the default indicating all UTFGrid Layers are queried.
+     * {Array} <OpenLayers.Layer.UTFGrid> 
+     */
+    layers: null,
+
     /** 
      * Property: element
      * {DOMElement} 
      */
     element: null,
+
+    /** 
+     * Property: debugElement
+     * {DOMElement} 
+     */
     debugElement: null,
     
-    /**
-     * Constructor: OpenLayers.Control.UTFGrid
-     * Parameters:
-     * options - {Object} Options for control.
+    /* Property: defaultHandlerOptions
+     * The default opts passed to the handler constructors
      */
     defaultHandlerOptions: {
         'delay': 300,
@@ -48,16 +83,30 @@ OpenLayers.Control.UTFGrid = OpenLayers.Class(OpenLayers.Control, {
         'stopDouble': false
     },
 
-    /* Property: handlerMode
+    /* APIProperty: handlerMode
      * Defaults to 'click'. Can be 'hover' or 'move'.
      */
     handlerMode: 'hover',
 
+    /**
+     * APIMethod: setHandler
+     * sets this.handlerMode and calls resetHandler()
+     *
+     * Parameters:
+     * hm - {String} Handler Mode string; 'click', 'hover' or 'move'.
+     */
     setHandler: function(hm) {
         this.handlerMode = hm;
         this.resetHandler();
     },
 
+    /**
+     * Method: resetHandler
+     * Deactivates the old hanlder and creates a new
+     * <OpenLayers.Handler> based on the mode specified in
+     * this.handlerMode
+     *
+     */
     resetHandler: function() {
         if (this.handler) {
             this.handler.deactivate();
@@ -112,6 +161,18 @@ OpenLayers.Control.UTFGrid = OpenLayers.Class(OpenLayers.Control, {
 
     /**
      * Method: handleEvent
+     * Internal method called when specified event is triggered.
+     * 
+     * This method does several things:
+     *
+     * Gets the lonLat of the event.
+     *
+     * Loops through the appropriate hit grid layers and gathers the attributes.
+     *
+     * Passes the attributes to the callback
+     *
+     * Parameters:
+     * evt - {<OpenLayers.Event>} 
      */
     handleEvent: function(evt) {
         if (evt == null) {
@@ -125,6 +186,7 @@ OpenLayers.Control.UTFGrid = OpenLayers.Class(OpenLayers.Control, {
         }    
         
         var layers = this.findLayers();
+        var globalAttrs = {};
         if (layers.length > 0) {
             var layer;
             for (var i=0, len=layers.length; i<len; i++) {
@@ -132,7 +194,7 @@ OpenLayers.Control.UTFGrid = OpenLayers.Class(OpenLayers.Control, {
                 var info = layer.getTileInfo( lonLat );
                 this.writeDebugInfo(info);
                 var tile = info.tile;
-                var attrs = null;
+                var localAttrs = null;
                 var resolution = layer.utfgridResolution || 4;
                 if (tile !== null && typeof(tile) !== 'undefined') {
                     var data = tile.json
@@ -142,15 +204,21 @@ OpenLayers.Control.UTFGrid = OpenLayers.Class(OpenLayers.Control, {
                             ].charCodeAt(
                                 Math.floor((info.i) / resolution)
                             ));
-                        attrs = data.data[data.keys[code]];
-                        this.callback(attrs);
+                        localAttrs = data.data[data.keys[code]];
+                        for (var property in localAttrs) {
+                            // If attribute names collide, last one takes it
+                            globalAttrs[property] = localAttrs[property];
+                        }
                     }
                 }
             }
+            this.callback(globalAttrs); // perhaps pass tile, lonLat?
         }
     },
 
-    /** Method: 
+    /** Method: writeDebugInfo
+     * Writes out debug info on event 
+     * Only fired off if this.debugElement is set
      *
      */
     writeDebugInfo: function(info) {
@@ -161,8 +229,6 @@ OpenLayers.Control.UTFGrid = OpenLayers.Class(OpenLayers.Control, {
         debug += "<li>globalcol :" + info.globalCol + "</li>";
         debug += "<li>gridrow :" + info.gridRow + "</li>";
         debug += "<li>gridcol :" + info.gridCol + "</li>";
-        debug += "<li>gridrow offset :" + info.gridRowOffset + "</li>";
-        debug += "<li>gridcol offset :" + info.gridColOffset + "</li>";
         debug += "</ul>";
         if (this.debugElement) {
             this.debugElement.innerHTML = debug;
@@ -170,9 +236,16 @@ OpenLayers.Control.UTFGrid = OpenLayers.Class(OpenLayers.Control, {
     },
 
     /**
-     * Method: callback
+     * APIMethod: callback
      * Takes the attrs and does somethings with them
-     * this is a default (intended to be overridden)
+     * The default behavior is to make a simple table
+     * and write to a div (defined by this.element)
+     *
+     * Parameters:
+     * attrs - {Object}
+     *
+     * Returns:
+     * {Boolean} - was the element updated?
      */
     callback: function(attrs) {
         if (attrs !== null && typeof(attrs) !== 'undefined') {
@@ -195,6 +268,12 @@ OpenLayers.Control.UTFGrid = OpenLayers.Class(OpenLayers.Control, {
      * number values.
      *  See the [utfgrid section of the mbtiles spec](https://github.com/mapbox/mbtiles-spec/blob/master/1.1/utfgrid.md)
      * for details.
+     *
+     * Parameters:
+     * key - {Integer}
+     *
+     * Returns:
+     * {Integer} Adjusted key for non-escaped chars
      */
     resolveCode: function(key) {
         if (key >= 93) key--;
@@ -205,6 +284,7 @@ OpenLayers.Control.UTFGrid = OpenLayers.Class(OpenLayers.Control, {
 
     /**
      * Method: reset
+     * Resets the element
      */
     reset: function(evt) {
         this.callback(null);
@@ -216,7 +296,15 @@ OpenLayers.Control.UTFGrid = OpenLayers.Class(OpenLayers.Control, {
      * Method: findLayers
      * Internal method to get the layers, independent of whether we are
      *     inspecting the map or using a client-provided array
-     *     MP TODO respect list of user-supplied candidates
+     *
+     * The default value of this.layers is null; this causes the 
+     * findLayers method to return ALL UTFGrid layers encountered.
+     *
+     * Parameters:
+     * None
+     *
+     * Returns:
+     * {Array} Layers to handle on each event
      */
     findLayers: function() {
         var candidates = this.layers || this.map.layers;