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

@@ -12,36 +12,60 @@ OpenLayers.State = {
 }
 
 /**
- * @class
- * 
  * @requires OpenLayers/Feature.js
  * @requires OpenLayers/Util.js
+ *
+ * Class: OpenLayers.Feature.Vector
+ * Vector features use the OpenLayers.Geometry classes as geometry description.
+ * They have an 'attributes' property, which is the data object, and a 'style'
+ * property, the default values of which are defined in the 
+ * <OpenLayers.Feature.Vector.style> objects.
+ * 
+ * Inherits from:
+ *  - <OpenLayers.Feature>
  */
 OpenLayers.Feature.Vector = OpenLayers.Class.create();
 OpenLayers.Feature.Vector.prototype =
   OpenLayers.Class.inherit( OpenLayers.Feature, {
 
-    /** @type String */
-    fid: null,
-    
-    /** @type OpenLayers.Geometry */
-    geometry:null,
-
-    /** @type Object */
-    attributes: null,
-
-    /** @type String */
-    state: null,
-    
-    /** @type Object */
-    style: null,
+    /** 
+	 * Property: fid 
+	 * {String} 
+	 */
+	fid: null,
     
     /** 
+	 * Property: geometry 
+	 * {<OpenLayers.Geometry>} 
+	 */
+	geometry: null,
+
+    /** 
+	 * Property: attributes 
+	 * {Object} 
+	 */
+	attributes: null,
+
+    /** 
+	 * Property: state 
+	 * {String} 
+	 */
+	state: null,
+    
+    /** 
+	 * Property: style 
+	 * {Object} 
+	 */
+	style: null,
+    
+    /** 
+     * Constructor: OpenLayers.Feature.Vector
      * Create a vector feature. 
-     * @constructor
      * 
-     * @param {OpenLayers.Geometry} geometry
-     * @param {Object} data
+     * Parameters:
+     * geometry - {<OpenLayers.Geometry>} 
+     * data - {Object} 
+     * style - {Object}
      */
     initialize: function(geometry, data, style) {
         OpenLayers.Feature.prototype.initialize.apply(this, [null, null, data]);
@@ -55,8 +79,9 @@ OpenLayers.Feature.Vector.prototype =
         this.style = style ? style : null; 
     },
     
-    /**
-     * 
+    /** 
+     * Method: destroy
+     * nullify references to prevent circular references and memory leaks
      */
     destroy: function() {
         if (this.layer) {
@@ -69,8 +94,10 @@ OpenLayers.Feature.Vector.prototype =
     },
     
    /**
-    * @returns An exact clone of this OpenLayers.Feature
-    * @type OpenLayers.Feature
+    * Method: clone
+    *
+    * Returns:
+    * <OpenLayers.Feature> An exact clone of this OpenLayers.Feature
     */
     clone: function (obj) {
         if (obj == null) {
@@ -84,30 +111,32 @@ OpenLayers.Feature.Vector.prototype =
     },
 
     /**
+     * Method: onScreen
      * HACK - we need to rewrite this for non-point geometry
-     * @returns null - we need to rewrite this for non-point geometry
-     * @type Boolean
+     * 
+     * Return:
+     * {Boolean} For now just returns null
      */
     onScreen:function() {
         return null;
     },
     
     /**
-     *
+     * Method: createMarker
      * HACK - we need to decide if all vector features should be able to
-     * create markers
+     *     create markers
      * 
-     * @returns null
-     * 
-     * @type OpenLayers.Marker
+     * Return:
+     * {<OpenLayers.Marker>} For now just returns null
      */
     createMarker: function() {
         return null;
     },
 
     /**
+     * Method: destroyMarker
      * HACK - we need to decide if all vector features should be able to
-     * delete markers
+     *     delete markers
      * 
      * If user overrides the createMarker() function, s/he should be able
      *   to also specify an alternative function for destroying it
@@ -117,22 +146,28 @@ OpenLayers.Feature.Vector.prototype =
     },
 
     /**
+     * Method: createPopup
      * HACK - we need to decide if all vector features should be able to
-     * create popups
+     *     create popups
      * 
-     * @returns null
+     * Return:
+     * {<OpenLayers.Popup>} For now just returns null
      */
     createPopup: function() {
         return null;
     },
 
     /**
-     * @param {OpenLayers.LonLat} lonlat
-     * @param {float} toleranceLon Optional tolerance in Geometric Coords
-     * @param {float} toleranceLat Optional tolerance in Geographic Coords
+     * Method: atPoint
+     * Determins whether the feature intersects with the specified location.
      * 
-     * @returns Whether or not the feature is at the specified location
-     * @type Boolean
+     * Parameters: 
+     * lonlat - {<OpenLayers.LonLat>} 
+     * toleranceLon - {float} Optional tolerance in Geometric Coords
+     * toleranceLat - {float} Optional tolerance in Geographic Coords
+     * 
+     * Returns:
+     * {Boolean} Whether or not the feature is at the specified location
      */
     atPoint: function(lonlat, toleranceLon, toleranceLat) {
         var atPoint = false;
@@ -144,7 +179,7 @@ OpenLayers.Feature.Vector.prototype =
     },
 
     /**
-     *
+     * Method: destroyPopup
      * HACK - we need to decide if all vector features should be able to
      * delete popups
      */
@@ -153,8 +188,11 @@ OpenLayers.Feature.Vector.prototype =
     },
     
     /**
+     * Method: toState
      * Sets the new state
-     * @param {String} state
+     *
+     * Parameters:
+     * state - {String} 
      */
     toState: function(state) {
         if (state == OpenLayers.State.UPDATE) {
@@ -196,7 +234,31 @@ OpenLayers.Feature.Vector.prototype =
 });
 
 
-// styles for feature rendering 
+/*
+ * Constant: OpenLayers.Feature.Vector.style
+ * OpenLayers features can have a number of 
+ * style attributes. The 'default' style will
+ * typically be used if no other style is specified.
+ *
+ * Default style properties:
+ *
+ *  - fillColor: "#ee9900",
+ *  - fillOpacity: 0.4, 
+ *  - hoverFillColor: "white",
+ *  - hoverFillOpacity: 0.8,
+ *  - strokeColor: "#ee9900",
+ *  - strokeOpacity: 1,
+ *  - strokeWidth: 1,
+ *  - strokeLinecap: "round",
+ *  - hoverStrokeColor: "red",
+ *  - hoverStrokeOpacity: 1,
+ *  - hoverStrokeWidth: 0.2,
+ *  - pointRadius: 6,
+ *  - hoverPointRadius: 1,
+ *  - hoverPointUnit: "%",
+ *  - pointerEvents: "visiblePainted"
+ */ 
+
 OpenLayers.Feature.Vector.style = {
     'default': {
         fillColor: "#ee9900",