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

@@ -4,38 +4,54 @@
 
 
 /**
- * @class
+ * Class: OpenLayers.Icon
  */
 OpenLayers.Icon = OpenLayers.Class.create();
 OpenLayers.Icon.prototype = {
     
-    /** image url
-    * @type String */
-    url: null,
-    
-    /** @type OpenLayers.Size */
-    size:null,
-
-    /** distance in pixels to offset the image when being rendered
-    * @type OpenLayers.Pixel */
-    offset: null,    
-    
-    /** Function to calculate the offset (based on the size) 
-     * @type OpenLayers.Pixel */
-    calculateOffset: null,    
-    
-    /** @type DOMElement */
-    imageDiv: null,
-
-    /** @type OpenLayers.Pixel */
-    px: null,
+    /** 
+	 * Property: url 
+	 * {String}  image url
+	 */
+	url: null,
     
     /** 
-    * @constructor
+	 * Property: size 
+	 * {<OpenLayers.Size>} 
+	 */
+	size: null,
+
+    /** 
+	 * Property: offset 
+	 * {<OpenLayers.Pixel>} distance in pixels to offset the image when being rendered
+	 */
+	offset: null,    
+    
+    /** 
+	 * Property: calculateOffset 
+	 * {<OpenLayers.Pixel>} Function to calculate the offset (based on the size) 
+	 */
+	calculateOffset: null,    
+    
+    /** 
+	 * Property: imageDiv 
+	 * {DOMElement} 
+	 */
+	imageDiv: null,
+
+    /** 
+	 * Property: px 
+	 * {<OpenLayers.Pixel>} 
+	 */
+	px: null,
+    
+    /** 
+    * Constructor: OpenLayers.Icon
+    * Creates an icon, which is an image tag in a div.  
     *
-    * @param {String} url
-    * @param {OpenLayers.Size} size
-    * @param {Function} calculateOffset
+    * url - {String} 
+    * size - {<OpenLayers.Size>} 
+    * calculateOffset - {Function} 
     */
     initialize: function(url, size, offset, calculateOffset) {
         this.url = url;
@@ -47,6 +63,10 @@ OpenLayers.Icon.prototype = {
         this.imageDiv = OpenLayers.Util.createAlphaImageDiv(id);
     },
     
+    /** 
+     * Method: destroy
+     * nullify references to prevent circular references and memory leaks
+     */
     destroy: function() {
         OpenLayers.Event.stopObservingElement(this.imageDiv.firstChild); 
         this.imageDiv.innerHTML = "";
@@ -54,8 +74,10 @@ OpenLayers.Icon.prototype = {
     },
 
     /** 
-    * @returns A fresh copy of the icon.
-    * @type OpenLayers.Icon
+    * Method: clone
+    * 
+    * Returns:
+    * {<OpenLayers.Icon>} A fresh copy of the icon.
     */
     clone: function() {
         return new OpenLayers.Icon(this.url, 
@@ -65,7 +87,9 @@ OpenLayers.Icon.prototype = {
     },
     
     /**
-     * @param {OpenLayers.Size} size
+     * Method: setSize
+     * 
+     * size - {<OpenLayers.Size>} 
      */
     setSize: function(size) {
         if (size != null) {
@@ -75,10 +99,14 @@ OpenLayers.Icon.prototype = {
     },
 
     /** 
-    * @param {OpenLayers.Pixel} px
+    * Method: draw
+    * Move the div to the given pixel.
     * 
-    * @return A new DOM Image of this icon set at the location passed-in
-    * @type DOMElement
+    * Parameters:
+    * px - {<OpenLayers.Pixel>} 
+    * 
+    * Returns:
+    * {DOMElement} A new DOM Image of this icon set at the location passed-in
     */
     draw: function(px) {
         OpenLayers.Util.modifyAlphaImageDiv(this.imageDiv, 
@@ -92,8 +120,12 @@ OpenLayers.Icon.prototype = {
     }, 
 
     
-    /** Change the icon's opacity
-     * @param {float} opacity
+    /** 
+     * Method: setOpacity
+     * Change the icon's opacity
+     *
+     * Parameters:
+     * opacity - {float} 
      */
     setOpacity: function(opacity) {
         OpenLayers.Util.modifyAlphaImageDiv(this.imageDiv, null, null, null, 
@@ -102,7 +134,11 @@ OpenLayers.Icon.prototype = {
     },
     
     /**
-    * @param {OpenLayers.Pixel} px
+    * Method: moveTo
+    * move icon to passed in px.
+    *
+    * Parameters:
+    * px - {<OpenLayers.Pixel>} 
     */
     moveTo: function (px) {
         //if no px passed in, use stored location
@@ -123,9 +159,12 @@ OpenLayers.Icon.prototype = {
         }
     },
     
-    /** Hide or show the icon
-     * 
-     * @param {Boolean} display
+    /** 
+     * Method: display
+     * Hide or show the icon
+     *
+     * Parameters:
+     * display - {Boolean} 
      */
     display: function(display) {
         this.imageDiv.style.display = (display) ? "" : "none";