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

@@ -4,32 +4,46 @@
 
 
 /**
- * @class
  * @requires OpenLayers/Events.js
  * @requires OpenLayers/Icon.js
+ * 
+ * Class: OpenLayers.Marker
+ * Instances of OpenLayers.Marker are a combination of a 
+ * <OpenLayers.LonLat> and an <OpenLayers.Icon>.
  */
 OpenLayers.Marker = OpenLayers.Class.create();
 OpenLayers.Marker.prototype = {
     
-    /** @type OpenLayers.Icon */
-    icon: null,
+    /** 
+	 * Property: icon 
+	 * {<OpenLayers.Icon>} 
+	 */
+	icon: null,
 
-    /** location of object
-    * @type OpenLayers.LonLat */
-    lonlat: null,
-    
-    /** @type OpenLayers.Events*/
-    events: null,
-    
-    /** @type OpenLayers.Map */
-    map: null,
+    /** 
+	 * Property: lonlat 
+	 * {<OpenLayers.LonLat>} location of object
+	 */
+	lonlat: null,
     
     /** 
-    * @constructor
-    *
-    * @param {OpenLayers.Icon} icon
-    * @param {OpenLayers.LonLat lonlat
-    */
+	 * Property: events 
+	 * {<OpenLayers.Events>}
+	 */
+	events: null,
+    
+    /** 
+	 * Property: map 
+	 * {<OpenLayers.Map>}
+	 */
+	map: null,
+    
+    /** 
+     * Constructor: OpenLayers.Marker
+     * Paraemeters:
+     * icon - {<OpenLayers.Icon>}
+     * lonlat - {<OpenLayers.LonLat>}
+     */
     initialize: function(lonlat, icon) {
         this.lonlat = lonlat;
         
@@ -58,18 +72,26 @@ OpenLayers.Marker.prototype = {
     },
     
     /** 
-    * @param {OpenLayers.Pixel} px
+    * Method: draw
+    * Calls draw on the icon, and returns that output.
     * 
-    * @return A new DOM Image with this marker's icon set at the 
-    *         location passed-in
-    * @type DOMElement
+    * Parameters:
+    * px - {<OpenLayers.Pixel>}
+    * 
+    * Return:
+    * {DOMElement} A new DOM Image with this marker's icon set at the 
+    * location passed-in
     */
     draw: function(px) {
         return this.icon.draw(px);
     }, 
 
     /**
-    * @param {OpenLayers.Pixel} px
+    * Method: moveTo
+    * Move the marker to the new location.
+    *
+    * Parameters:
+    * px - {<OpenLayers.Pixel>}
     */
     moveTo: function (px) {
         if ((px != null) && (this.icon != null)) {
@@ -79,8 +101,10 @@ OpenLayers.Marker.prototype = {
     },
 
     /**
-     * @returns Whether or not the marker is currently visible on screen.
-     * @type Boolean
+     * Method: onScreen
+     *
+     * Return:
+     * {Boolean} Whether or not the marker is currently visible on screen.
      */
     onScreen:function() {
         
@@ -93,7 +117,10 @@ OpenLayers.Marker.prototype = {
     },
     
     /**
-     * @param {float} inflate
+     * Method: inflate
+     *
+     * Parameters:
+     * inflate - {float}
      */
     inflate: function(inflate) {
         if (this.icon) {
@@ -103,18 +130,23 @@ OpenLayers.Marker.prototype = {
         }        
     },
     
-    /** Change the opacity of the marker by changin the opacity of 
+    /** 
+     * Method: setOpacity
+     * Change the opacity of the marker by changin the opacity of 
      *   its icon
      * 
-     * @param {float} opacity Specified as fraction (0.4, etc)
+     * Parameters:
+     * opacity - {float}  Specified as fraction (0.4, etc)
      */
     setOpacity: function(opacity) {
         this.icon.setOpacity(opacity);
     },
 
-    /** Hide or show the icon
+    /** 
+     * Method: display
+     * Hide or show the icon
      * 
-     * @param {Boolean} display
+     * display - {Boolean} 
      */
     display: function(display) {
         this.icon.display(display);
@@ -125,9 +157,12 @@ OpenLayers.Marker.prototype = {
 };
 
 
-/** 
- * @returns A default OpenLayers.Icon to use for a marker
- * @type OpenLayers.Icon
+/**
+ * Function: defaultIcon
+ * Creates a default <OpenLayers.Icon>.
+ * 
+ * Returns:
+ * {<OpenLayers.Icon>} A default OpenLayers.Icon to use for a marker
  */
 OpenLayers.Marker.defaultIcon = function() {
     var url = OpenLayers.Util.getImagesLocation() + "marker.png";