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/Tile.js

@@ -4,14 +4,15 @@
 
 
 /*
- * @class 
  * @requires OpenLayers/Util.js
- * 
+ *
+ * Class: OpenLayers.Tile 
  * This is a class designed to designate a single tile, however
  * it is explicitly designed to do relatively little. Tiles store information
  * about themselves -- such as the URL that they are related to, and their 
  * size - but do not add themselves to the layer div automatically, for 
- * example.
+ * example. Create a new tile with the <OpenLayers.Tile> constructor, or 
+ * a subclass. 
  * 
  * TBD 3.0 - remove reference to url in above paragraph
  * 
@@ -19,43 +20,65 @@
 OpenLayers.Tile = OpenLayers.Class.create();
 OpenLayers.Tile.prototype = {
     
-    /** @type String */
-    id: null,
+    /** 
+	 * Property: id 
+	 * {String} null
+	 */
+	id: null,
     
-    /** @type OpenLayers.Layer */
-    layer: null,
+    /** 
+	 * Property: layer 
+	 * {<OpenLayers.Layer>} layer the tile is attached to 
+	 */
+	layer: null,
     
-    /** TBD 3.0 
-     * @deprecated The base tile class does not need an url. This should be 
-     *              handled in subclasses. Does not belong here.
-     * 
-     * @type String url of the request */
-    url:null,
+    /**
+     * Property: url
+     * {String} url of the request 
+     *
+     * TBD 3.0 
+     * Deprecated. The base tile class does not need an url. This should be 
+     * handled in subclasses. Does not belong here.
+     */
+    url: null,
 
-    /** @type OpenLayers.Bounds */
-    bounds:null,
+    /** 
+	 * APIProperty: bounds 
+	 * {<OpenLayers.Bounds>} null
+	 */
+	bounds: null,
     
-    /** @type OpenLayers.Size */
-    size:null,
+    /** 
+	 * Property: size 
+	 * {<OpenLayers.Size>} null
+	 */
+	size: null,
     
-    /** Top Left pixel of the tile
-    * @type OpenLayers.Pixel */
-    position:null,
+    /** 
+	 * Property: position 
+	 * {<OpenLayers.Pixel>} Top Left pixel of the tile
+	 */	
+    position: null,
 
-    /** @type Boolean */
-    drawn: false,
+    /** 
+	 * Property: drawn 
+	 * {Boolean} false
+	 */
+	drawn: false,
 
     /** TBD 3.0 -- remove 'url' from the list of parameters to the constructor.
      *             there is no need for the base tile class to have a url.
      * 
-    * @constructor
-    *
-    * @param {OpenLayers.Layer} layer
-    * @param {OpenLayers.Pixel} position
-    * @param {OpenLayers.Bounds} bounds
-    * @param {String} url
-    * @param {OpenLayers.Size} size
-    */   
+     * Constructor: OpenLayers.Tile
+     * Constructor for a new <OpenLayers.Tile> instance.
+     * 
+     * Parameters:
+     * layer - {<OpenLayers.Layer>} layer that the tile will go in.
+     * position - {<OpenLayers.Pixel>}
+     * bounds - {<OpenLayers.Bounds>}
+     * url - {<String>}
+     * size - {<OpenLayers.Size>}
+     */   
     initialize: function(layer, position, bounds, url, size) {
         this.layer = layer;
         this.position = position;
@@ -67,8 +90,10 @@ OpenLayers.Tile.prototype = {
         this.id = OpenLayers.Util.createUniqueID("Tile_");
     },
     
-    /** nullify references to prevent circular references and memory leaks
-    */
+    /** 
+     * APIMethod: destroy
+     * nullify references to prevent circular references and memory leaks
+     */
     destroy:function() {
         this.layer  = null;
         this.bounds = null;
@@ -77,14 +102,15 @@ OpenLayers.Tile.prototype = {
     },
 
     /**
+     * Method: draw
      * Clear whatever is currently in the tile, then return whether or not 
      *  it should actually be re-drawn.
      * 
-     * @returns Whether or not the tile should actually be drawn. Note that 
+     * Return:
+     * {Boolean} Whether or not the tile should actually be drawn. Note that 
      *           this is not really the best way of doing things, but such is 
      *           the way the code has been developed. Subclasses call this and
      *           depend on the return to know if they should draw or not.
-     * @type Boolean
      */
     draw: function() {
         
@@ -112,10 +138,13 @@ OpenLayers.Tile.prototype = {
     },
     
     /** 
-     * @param {OpenLayers.Bounds}
-     * @param {OpenLayers.pixel} position
-     * @param {Boolean} redraw Redraw tile after moving? 
-     *                         Default is true
+     * Method: moveTo
+     * Reposition the tile.
+     *
+     * Parameters:
+     * bounds - {<OpenLayers.Bounds>}
+     * position - {<OpenLayers.Pixel>}
+     * redraw - {Boolean} Call draw method on tile after moving? Default is true
      */
     moveTo: function (bounds, position, redraw) {
         if (redraw == null) {
@@ -130,13 +159,27 @@ OpenLayers.Tile.prototype = {
         }
     },
 
-    /** Clear the tile of any bounds/position-related data so that it can 
-     *   be reused in a new location.
+    /** 
+     * Method: clear
+     * Clear the tile of any bounds/position-related data so that it can 
+     * be reused in a new location.
      */
     clear: function() {
         this.drawn = false;
     },
     
+    /**   
+     * Method: getBoundsFromBaseLayer
+     * Take the pixel locations of the corner of the tile, and pass them to the base layer 
+     * and ask for the location of those pixels, so that displaying tiles over Google
+     * works fine.
+     *
+     * Parameters:
+     * position - {<OpenLayers.Pixel>}
+     *
+     * Return:
+     * bounds - {<OpenLayers.Bounds>} 
+     */
     getBoundsFromBaseLayer: function(position) {
         var topLeft = this.layer.map.getLonLatFromLayerPx(position); 
         var bottomRightPx = position.clone();
@@ -159,5 +202,3 @@ OpenLayers.Tile.prototype = {
     /** @final @type String */
     CLASS_NAME: "OpenLayers.Tile"
 };
-
-