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

@@ -4,41 +4,69 @@
 
 
 /**
- * @class
- * 
  * @requires OpenLayers/Util.js
  * @requires OpenLayers/Marker.js
+ *
+ * Class: OpenLayers.Feature
+ * Features are combinations of geography and attributes. The OpenLayers.Feature
+ * class specifically combines a marker and a lonlat.
  */
 OpenLayers.Feature = OpenLayers.Class.create();
 OpenLayers.Feature.prototype= {
 
-    /** @type OpenLayers.Events */
-    events:null,
-
-    /** @type OpenLayers.Layer */
-    layer: null,
-
-    /** @type String */
-    id: null,
-    
-    /** @type OpenLayers.LonLat */
-    lonlat:null,
-
-    /** @type Object */
-    data:null,
-
-    /** @type OpenLayers.Marker */
-    marker: null,
-
-    /** @type OpenLayers.Popup */
-    popup: null,
+    /** 
+	 * Property: events 
+	 * {<OpenLayers.Events>} 
+	 */
+	events: null,
 
     /** 
-     * @constructor
+	 * Property: layer 
+	 * {<OpenLayers.Layer>} 
+	 */
+	layer: null,
+
+    /** 
+	 * Property: id 
+	 * {String} 
+	 */
+	id: null,
+    
+    /** 
+	 * Property: lonlat 
+	 * {<OpenLayers.LonLat>} 
+	 */
+	lonlat: null,
+
+    /** 
+	 * Property: data 
+	 * {Object} 
+	 */
+	data: null,
+
+    /** 
+	 * Property: marker 
+	 * {<OpenLayers.Marker>} 
+	 */
+	marker: null,
+
+    /** 
+	 * Property: popup 
+	 * {<OpenLayers.Popup>} 
+	 */
+	popup: null,
+
+    /** 
+     * Constructor: OpenLayers.Feature
+     * Constructor for features.
+     *
+     * Parameters:
+     * layer - {<OpenLayers.Layer>} 
+     * lonlat - {<OpenLayers.LonLat>} 
+     * data - {Object} 
      * 
-     * @param {OpenLayers.Layer} layer
-     * @param {OpenLayers.LonLat} lonlat
-     * @param {Object} data
+     * Return:
+     * {<OpenLayers.Feature>}
      */
     initialize: function(layer, lonlat, data) {
         this.layer = layer;
@@ -47,8 +75,9 @@ OpenLayers.Feature.prototype= {
         this.id = OpenLayers.Util.createUniqueID(this.CLASS_NAME + "_"); 
     },
 
-    /**
-     * 
+    /** 
+     * Method: destroy
+     * nullify references to prevent circular references and memory leaks
      */
     destroy: function() {
 
@@ -79,9 +108,11 @@ OpenLayers.Feature.prototype= {
     },
     
     /**
-     * @returns Whether or not the feature is currently visible on screen
+     * Method: onScreen
+     * 
+     * Returns:
+     * {Boolean} Whether or not the feature is currently visible on screen
      *           (based on its 'lonlat' property)
-     * @type Boolean
      */
     onScreen:function() {
         
@@ -95,13 +126,16 @@ OpenLayers.Feature.prototype= {
     
 
     /**
-     * @returns A Marker Object created from the 'lonlat' and 'icon' properties
+     * Method: createMarker
+     * Based on the data associated with the Feature, create and return a marker object.
+     *
+     * Return: 
+     * {<OpenLayers.Marker>} A Marker Object created from the 'lonlat' and 'icon' properties
      *          set in this.data. If no 'lonlat' is set, returns null. If no
      *          'icon' is set, OpenLayers.Marker() will load the default image.
      *          
-     *          Note: this.marker is set to return value
+     *          Note - this.marker is set to return value
      * 
-     * @type OpenLayers.Marker
      */
     createMarker: function() {
 
@@ -113,7 +147,10 @@ OpenLayers.Feature.prototype= {
         return this.marker;
     },
 
-    /** If user overrides the createMarker() function, s/he should be able
+    /**
+     * Method: destroyMarker
+     * Destroys marker.
+     * If user overrides the createMarker() function, s/he should be able
      *   to also specify an alternative function for destroying it
      */
     destroyMarker: function() {
@@ -121,17 +158,22 @@ OpenLayers.Feature.prototype= {
     },
 
     /**
-     * @param {Boolean} closeBox create popup with closebox or not
-     * @returns A Popup Object created from the 'lonlat', 'popupSize',
-     *          and 'popupContentHTML' properties set in this.data. It uses
-     *          this.marker.icon as default anchor. 
-     *          
-     *          If no 'lonlat' is set, returns null. 
-     *          If no this.marker has been created, no anchor is sent.
+     * Method: createPopup
+     *  Creates a popup object created from the 'lonlat', 'popupSize',
+     *  and 'popupContentHTML' properties set in this.data. It uses
+     *  this.marker.icon as default anchor. 
+     *  
+     *  If no 'lonlat' is set, returns null. 
+     *  If no this.marker has been created, no anchor is sent.
      * 
-     *          Note: this.popup is set to return value
+     *  Note - this.popup is set to return value
+     * 
+     * Parameters: 
+     * closeBox - {Boolean} create popup with closebox or not
+     * 
+     * Returns:
+     * {<OpenLayers.Popup.AnchoredBubble>} 
      * 
-     * @type OpenLayers.Popup.AnchoredBubble
      */
     createPopup: function(closeBox) {
 
@@ -150,7 +192,11 @@ OpenLayers.Feature.prototype= {
     },
 
     
-    /** As with the marker, if user overrides the createPopup() function, s/he 
+    /**
+     * Method: destroyPopup
+     * Destroys the popup created via createPopup.
+     *
+     * As with the marker, if user overrides the createPopup() function, s/he 
      *   should also be able to override the destruction
      */
     destroyPopup: function() {