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

@@ -4,39 +4,54 @@
 
 
 /**
- * @class
- * 
  * @requires OpenLayers/Tile.js
+ * 
+ * Class: OpenLayers.Tile.Image
+ * Instances of OpenLayers.Tile.Image are used to manage the image tiles
+ * used by various layers.  Create a new image tile with the
+ * <OpenLayers.Tile.Image> constructor.
+ *
+ * Inherits from:
+ *  - <OpenLayers.Tile>
  */
 OpenLayers.Tile.Image = OpenLayers.Class.create();
 OpenLayers.Tile.Image.prototype = 
   OpenLayers.Class.inherit( OpenLayers.Tile, {
 
-    /** @type String */
+    /** 
+     * Property: url
+     * {String} The URL of the image being requested. No default. Filled in by
+     * layer.getURL() function. 
+     */
     url: null,
     
-    /** @type DOMElement img */
+    /** 
+     * Property: imgDiv
+     * {DOMElement} The div element which wraps the image.
+     */
     imgDiv: null,
 
     /**
-     * The image element is appended to the frame.  Any gutter on the image 
-     * will be hidden behind the frame. 
-     * 
-     * @type DOMElement div */ 
+     * Property: frame
+     * {DOMElement} The image element is appended to the frame.  Any gutter on
+     * the image will be hidden behind the frame. 
+     */ 
     frame: null, 
 
     /** TBD 3.0 - reorder the parameters to the init function to put URL 
      *             as last, so we can continue to call tile.initialize() 
      *             without changing the arguments. 
      * 
-    * @constructor
-    *
-    * @param {OpenLayers.Grid} layer
-    * @param {OpenLayers.Pixel} position
-    * @param {OpenLayers.Bounds} bounds
-    * @param {String} url
-    * @param {OpenLayers.Size} size
-    */
+     * Constructor: OpenLayers.Tile.Image
+     * Constructor for a new <OpenLayers.Tile.Image> 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) {
         OpenLayers.Tile.prototype.initialize.apply(this, arguments);
 
@@ -47,8 +62,9 @@ OpenLayers.Tile.Image.prototype =
         this.frame.style.position = 'absolute'; 
     },
 
-    /**
-     * 
+    /** 
+     * APIMethod: destroy
+     * nullify references to prevent circular references and memory leaks
      */
     destroy: function() {
         if (this.imgDiv != null)  {
@@ -67,7 +83,11 @@ OpenLayers.Tile.Image.prototype =
     },
 
     /**
+     * Method: draw
+     * Check that a tile should be drawn, and draw it.
      * 
+     * Return:
+     * {Boolean} Always returns true.
      */
     draw:function() {
         if (this.layer != this.layer.map.baseLayer && this.layer.reproject) {
@@ -99,7 +119,9 @@ OpenLayers.Tile.Image.prototype =
         return true;
     },
 
-    /** Clear the tile of any bounds/position-related data so that it can 
+    /** 
+     * Method: clear
+     *  Clear the tile of any bounds/position-related data so that it can 
      *   be reused in a new location.
      */
     clear: function() {
@@ -110,9 +132,13 @@ OpenLayers.Tile.Image.prototype =
     },
 
     /** 
-     * @param {OpenLayers.Bounds}
-     * @param {OpenLayers.pixel} position
-     * @param {Boolean} redraw
+     * 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 (this.layer != this.layer.map.baseLayer && this.layer.reproject) {
@@ -123,7 +149,8 @@ OpenLayers.Tile.Image.prototype =
     },
 
     /**
-     * 
+     * Method: initImgDiv
+     * Creates the imgDiv property on the tile.
      */
     initImgDiv: function() {
         if (this.layer.alpha) {
@@ -173,6 +200,7 @@ OpenLayers.Tile.Image.prototype =
     },
 
     /**
+     * Method: checkImgURL
      * Make sure that the image that just loaded is the one this tile is meant
      * to display, since panning/zooming might have changed the tile's URL in
      * the meantime. If the tile URL did change before the image loaded, set
@@ -187,8 +215,6 @@ OpenLayers.Tile.Image.prototype =
      * 
      * See discussion in the thread at 
      * http://openlayers.org/pipermail/dev/2007-January/000205.html
-     *
-     * @private
      */
     checkImgURL: function () {
         // Sometimes our image will load after it has already been removed
@@ -201,7 +227,10 @@ OpenLayers.Tile.Image.prototype =
         }
     },
 
-    /** @final @type String */
+    /**
+     * Constant: CLASS_NAME
+     * {String} Name of class.
+     */
     CLASS_NAME: "OpenLayers.Tile.Image"
   }
 );