Documentation improvements provided by Glen Stampoultzis. (Thanks Glen!) Closes

#825, #836.


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

lib/OpenLayers/Icon.js

@@ -5,6 +5,15 @@
 
 /**
  * Class: OpenLayers.Icon
+ * 
+ * The icon represents a graphical icon on the screen.  Typically used in
+ * conjunction with a <OpenLayers.Marker> to represent markers on a screen.
+ *
+ * An icon has a url, size and position.  It also contains an offset which 
+ * allows the center point to be represented correctly.  This can be
+ * provided either as a fixed offset or a function provided to calculate
+ * the desired offset. 
+ * 
  */
 OpenLayers.Icon = OpenLayers.Class.create();
 OpenLayers.Icon.prototype = {
@@ -65,7 +74,8 @@ OpenLayers.Icon.prototype = {
     
     /** 
      * Method: destroy
-     * nullify references to prevent circular references and memory leaks
+     * Nullify references and remove event listeners to prevent circular 
+     * references and memory leaks
      */
     destroy: function() {
         OpenLayers.Event.stopObservingElement(this.imageDiv.firstChild);