Merge all changes from the naturaldocs sandbox. This brings all the work that

has been done in the NaturalDocs branch back to trunk. Thanks to everyone who
helped out in making this happen. (I could list people, but the list would
be long, and I'm already mentally on vacation.)


git-svn-id: http://svn.openlayers.org/trunk/openlayers@3545 dc9f47b5-9b13-0410-9fdd-eb0c1a62fdaf

lib/OpenLayers/Layer/Grid.js

@@ -4,32 +4,46 @@
 
 
 /**
- * @class
- * 
  * @requires OpenLayers/Layer/HTTPRequest.js
+ * 
+ * Class: OpenLayers.Layer.Grid
+ * Base class for layers that use a lattice of tiles.  Create a new grid
+ * layer with the <OpenLayers.Layer.Grid> constructor.
+ *
+ * Inherits from:
+ *  - <OpenLayers.Layer.HTTPRequest>
  */
 OpenLayers.Layer.Grid = OpenLayers.Class.create();
 OpenLayers.Layer.Grid.prototype = 
   OpenLayers.Class.inherit( OpenLayers.Layer.HTTPRequest, {
     
-    /** @type OpenLayers.Size */
+    /**
+     * APIProperty: tileSize
+     * {<OpenLayers.Size>}
+     */
     tileSize: null,
     
-    /** this is an array of rows, each row is an array of tiles
-     * 
-     * @type Array(Array) */
+    /**
+     * Property: grid
+     * {Array} This is an array of rows, each row is an array of tiles
+     */
     grid: null,
 
-    /** @type Integer */
+    /**
+     * APIProperty: buffer
+     * {Integer}
+     */
     buffer: 2,
 
     /**
-     * @constructor
-     * 
-     * @param {String} name
-     * @param {String} url
-     * @param {Object} params
-     * @param {Object} options Hashtable of extra options to tag onto the layer
+     * Constructor: OpenLayers.Layer.Grid
+     * Create a new grid layer
+     *
+     * Parameters:
+     * name - {String}
+     * url - {String}
+     * params - {Object}
+     * options - {Object} Hashtable of extra options to tag onto the layer
     */
     initialize: function(name, url, params, options) {
         OpenLayers.Layer.HTTPRequest.prototype.initialize.apply(this, 
@@ -37,8 +51,9 @@ OpenLayers.Layer.Grid.prototype =
         this.grid = new Array();
     },
 
-    /** on destroy, clear the grid.
-     *
+    /**
+     * APIMethod: destroy
+     * Deconstruct the layer and clear the grid.
      */
     destroy: function() {
         this.clearGrid();
@@ -47,10 +62,10 @@ OpenLayers.Layer.Grid.prototype =
         OpenLayers.Layer.HTTPRequest.prototype.destroy.apply(this, arguments); 
     },
 
-    /** go through and remove all tiles from the grid, calling
+    /**
+     * Method: clearGrid
+     * Go through and remove all tiles from the grid, calling
      *    destroy() on each of them to kill circular references
-     * 
-     * @private
      */
     clearGrid:function() {
         if (this.grid) {
@@ -65,10 +80,14 @@ OpenLayers.Layer.Grid.prototype =
     },
 
     /**
-     * @param {Object} obj
+     * APIMethod: clone
+     * Create a clone of this layer
+     *
+     * Parameters:
+     * obj - {Object} Is this ever used?
      * 
-     * @returns An exact clone of this OpenLayers.Layer.Grid
-     * @type OpenLayers.Layer.Grid
+     * Return:
+     * {<OpenLayers.Layer.Grid>} An exact clone of this OpenLayers.Layer.Grid
      */
     clone: function (obj) {
         
@@ -93,10 +112,13 @@ OpenLayers.Layer.Grid.prototype =
         return obj;
     },    
 
-    /** When the layer is added to a map, then we can ask the map for
+    /**
+     * Method: setMap
+     * When the layer is added to a map, then we can ask the map for
      *   its default tile size
-     * 
-     * @param {OpenLayers.Map} map
+     *
+     * Parameters:
+     * map - {<OpenLayers.Map>}
      */
     setMap: function(map) {
         OpenLayers.Layer.HTTPRequest.prototype.setMap.apply(this, arguments);
@@ -105,13 +127,16 @@ OpenLayers.Layer.Grid.prototype =
         }
     },
 
-    /** This function is called whenever the map is moved. All the moving
+    /**
+     * Method: moveTo
+     * This function is called whenever the map is moved. All the moving
      * of actual 'tiles' is done by the map, but moveTo's role is to accept
      * a bounds and make sure the data that that bounds requires is pre-loaded.
-     * 
-     * @param {OpenLayers.Bounds} bounds
-     * @param {Boolean} zoomChanged
-     * @param {Boolean} dragging
+     *
+     * Parameters:
+     * bounds - {<OpenLayers.Bounds>}
+     * zoomChanged - {Boolean}
+     * dragging - {Boolean}
      */
     moveTo:function(bounds, zoomChanged, dragging) {
         OpenLayers.Layer.HTTPRequest.prototype.moveTo.apply(this, arguments);
@@ -157,12 +182,13 @@ OpenLayers.Layer.Grid.prototype =
     },
     
     /**
-     * @private
+     * Method: getGridBounds
+     * Get the bounds of the grid
      * 
-     * @returns A Bounds object representing the bounds of all the currently 
-     *           loaded tiles (including those partially or not at all seen 
-     *           onscreen)
-     * @type OpenLayers.Bounds
+     * Return:
+     * {<OpenLayers.Bounds>} A Bounds object representing the bounds of all the
+     * currently loaded tiles (including those partially or not at all seen 
+     * onscreen)
      */
     getGridBounds:function() {
         
@@ -179,7 +205,8 @@ OpenLayers.Layer.Grid.prototype =
     },
 
     /**
-     * @private
+     * Method: _initTiles
+     * Initialize the tiles
      */
     _initTiles:function() {
         
@@ -280,9 +307,8 @@ OpenLayers.Layer.Grid.prototype =
         this.spiralTileLoad();
     },
     
-    /** 
-     * @private 
-     * 
+    /**
+     * Method: spiralTileLoad
      *   Starts at the top right corner of the grid and proceeds in a spiral 
      *    towards the center, adding tiles one at a time to the beginning of a 
      *    queue. 
@@ -355,23 +381,27 @@ OpenLayers.Layer.Grid.prototype =
     },
 
     /**
-     * addTile gives subclasses of Grid the opportunity to create an 
+     * APIMethod: addTile
+     * Gives subclasses of Grid the opportunity to create an 
      * OpenLayer.Tile of their choosing. The implementer should initialize 
      * the new tile and take whatever steps necessary to display it.
      *
-     * @param {OpenLayers.Bounds} bounds
+     * Parameters
+     * bounds - {<OpenLayers.Bounds>}
      *
-     * @returns The added OpenLayers.Tile
-     * @type OpenLayers.Tile
+     * Return:
+     * {<OpenLayers.Tile>} The added OpenLayers.Tile
      */
     addTile:function(bounds, position) {
         // Should be implemented by subclasses
     },
 
     /**
+     * APIMethod: mergeNewParams
      * Once params have been changed, we will need to re-init our tiles
      *
-     * @param {Object} newParams Hashtable of new params to use
+     * Parameters:
+     * newParams - {Object} Hashtable of new params to use
      */
     mergeNewParams:function(newArguments) {
         OpenLayers.Layer.HTTPRequest.prototype.mergeNewParams.apply(this,
@@ -384,9 +414,11 @@ OpenLayers.Layer.Grid.prototype =
 
     
     /**
-     * @private 
-     * 
-     * @param {Boolean} prepend if true, prepend to beginning.
+     * Method: shiftRow
+     * Shifty grid work
+     *
+     * Parameters:
+     * prepend - {Boolean} if true, prepend to beginning.
      *                          if false, then append to end
      */
     shiftRow:function(prepend) {
@@ -417,9 +449,11 @@ OpenLayers.Layer.Grid.prototype =
     },
 
     /**
-     * @private
-     * 
-     * @param {Boolean} prepend if true, prepend to beginning.
+     * Method: shiftColumn
+     * Shift grid work in the other dimension
+     *
+     * Parameters:
+     * prepend - {Boolean} if true, prepend to beginning.
      *                          if false, then append to end
      */
     shiftColumn: function(prepend) {
@@ -448,6 +482,9 @@ OpenLayers.Layer.Grid.prototype =
         }
     },
     
-    /** @final @type String */
+    /**
+     * Constant: CLASS_NAME
+     * {String} Name of this class
+     */
     CLASS_NAME: "OpenLayers.Layer.Grid"
 });