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

@@ -9,14 +9,29 @@
  * 
  * Class: OpenLayers.Marker
  * Instances of OpenLayers.Marker are a combination of a 
- * <OpenLayers.LonLat> and an <OpenLayers.Icon>.
+ * <OpenLayers.LonLat> and an <OpenLayers.Icon>.  
+ *
+ * Markers are generally added to a special layer called
+ * <OpenLayers.Layer.Makers>.
+ *
+ * Example:
+ * (code)
+ * var markers = new OpenLayers.Layer.Markers( "Markers" );
+ * map.addLayer(markers);
+ *
+ * var size = new OpenLayers.Size(10,17);
+ * var offset = new OpenLayers.Pixel(-(size.w/2), -size.h);
+ * var icon = new OpenLayers.Icon('http://boston.openguides.org/markers/AQUA.png',size,offset);
+ * markers.addMarker(new OpenLayers.Marker(new OpenLayers.LonLat(0,0),icon));
+ *
+ * (end)
  */
 OpenLayers.Marker = OpenLayers.Class.create();
 OpenLayers.Marker.prototype = {
     
     /** 
      * Property: icon 
-     * {<OpenLayers.Icon>} 
+     * {<OpenLayers.Icon>} The icon used by this marker.
      */
     icon: null,
 
@@ -28,21 +43,21 @@ OpenLayers.Marker.prototype = {
     
     /** 
      * Property: events 
-     * {<OpenLayers.Events>}
+     * {<OpenLayers.Events>} the event handler.
      */
     events: null,
     
     /** 
      * Property: map 
-     * {<OpenLayers.Map>}
+     * {<OpenLayers.Map>} the map this marker is attached to
      */
     map: null,
     
     /** 
      * Constructor: OpenLayers.Marker
      * Paraemeters:
-     * icon - {<OpenLayers.Icon>}
-     * lonlat - {<OpenLayers.LonLat>}
+     * icon - {<OpenLayers.Icon>}  the icon for this marker
+     * lonlat - {<OpenLayers.LonLat>} the position of this marker
      */
     initialize: function(lonlat, icon) {
         this.lonlat = lonlat;
@@ -91,7 +106,7 @@ OpenLayers.Marker.prototype = {
     * Move the marker to the new location.
     *
     * Parameters:
-    * px - {<OpenLayers.Pixel>}
+    * px - {<OpenLayers.Pixel>} the pixel position to move to
     */
     moveTo: function (px) {
         if ((px != null) && (this.icon != null)) {
@@ -118,9 +133,11 @@ OpenLayers.Marker.prototype = {
     
     /**
      * Method: inflate
+     * Englarges the markers icon by the specified ratio.
      *
      * Parameters:
-     * inflate - {float}
+     * inflate - {float} the ratio to enlarge the marker by (passing 2
+     *                   will double the size).
      */
     inflate: function(inflate) {
         if (this.icon) {