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

@@ -3,71 +3,107 @@
  * for the full text of the license. */
 
 /**
- * @class
- *
  * @requires OpenLayers/Layer.js
  * @requires OpenLayers/Renderer.js
  * @requires OpenLayers/Feature/Vector.js
+ * 
+ * Class: OpenLayers.Layer.Vector
+ * Instances of OpenLayers.Layer.Vector are used to render vector data from
+ * a variety of sources. Create a new image layer with the
+ * <OpenLayers.Layer.Vector> constructor.
+ *
+ * Inherits from:
+ *  - <OpenLayers.Layer>
  */
 OpenLayers.Layer.Vector = OpenLayers.Class.create();
 OpenLayers.Layer.Vector.prototype =
   OpenLayers.Class.inherit(OpenLayers.Layer, {
 
-    /** @type Boolean */
+    /**
+     * APIProperty: isBaseLayer
+     * {Boolean} The layer is a base layer.  Default is true.  Set this property
+     * in the layer options
+     */
     isBaseLayer: false,
 
-    /** @type Boolean */
+    /** 
+     * APIProperty: isFixed
+     * {Boolean} Whether the layer remains in one place while dragging the
+     * map.
+     */
     isFixed: false,
 
-    /** @type Boolean */
+    /** 
+     * APIProperty: isVector
+     * {Boolean} Whether the layer is a vector layer.
+     */
     isVector: true,
 
-    /** @type Array(OpenLayer.Feature.Vector) */
+    /** 
+     * APIProperty: features
+     * Array({<OpenLayers.Feature.Vector>}) 
+     */
     features: null,
     
-    /** @type Array(OpenLayers.Feature.Vector) */
+    /** 
+     * Property: selectedFeatures
+     * Array({<OpenLayers.Feature.Vector>}) 
+     */
     selectedFeatures: null,
 
-    /** @type {Boolean} */
+    /**
+     * APIProperty: reportError
+     * {Boolean} report error message via alert() when loading of renderers
+     * fails.
+     */
     reportError: true, 
 
-    /** @type {Object} */
+    /** 
+     * APIProperty: style
+     * {Object} Default style for the layer
+     */
     style: null,
 
     /**
-     * List of supported Renderer classes. Add to this list to
+     * Property: renderers
+     * Array({String}) List of supported Renderer classes. Add to this list to
      * add support for additional renderers. This list is ordered:
      * the first renderer which returns true for the  'supported()'
      * method will be used, if not defined in the 'renderer' option.
-     * 
-     * @type {Array(String)} 
      */
     renderers: ['SVG', 'VML'],
     
-    /** @type OpenLayers.Renderer */
+    /** 
+     * Property: renderer
+     * {<OpenLayers.Renderer>}
+     */
     renderer: null,
    
     /** 
-     * geometryType allows you to limit the types of geometries this
-     * layer supports. This should be set to something like 
+     * APIProperty: geometryType
+     * {String} geometryType allows you to limit the types of geometries this
+     * layer supports. This should be set to something like
      * "OpenLayers.Geometry.Point" to limit types.
-     * 
-     * @type string 
      */
     geometryType: null,
 
-    /** Whether the Vector Layer features have been drawn yet.
-     *
-     * @type boolean 
+    /** 
+     * Property: drawn
+     * {Boolean} Whether the Vector Layer features have been drawn yet.
      */
     drawn: false,
 
     /**
-     * @constructor
+     * Constructor: OpenLayers.Layer.Vector
+     * Create a new vector layer
      *
-     * @param {String} name
-     * @param {Object} options Hashtable of extra options to tag onto the layer.
-     * Options renderer {Object}: Typically SVGRenderer or VMLRenderer.
+     * Parameters:
+     * name - {String} A name for the layer
+     * options - {Object} options Object with non-default properties to set on
+     *           the layer.
+     *
+     * Return:
+     * {<OpenLayers.Layer.Vector>} A new vector layer
      */
     initialize: function(name, options) {
 
@@ -92,7 +128,8 @@ OpenLayers.Layer.Vector.prototype =
     },
 
     /**
-     * 
+     * APIMethod: destroy
+     * Destroy this layer
      */
     destroy: function() {
         OpenLayers.Layer.prototype.destroy.apply(this, arguments);  
@@ -108,11 +145,10 @@ OpenLayers.Layer.Vector.prototype =
         this.drawn = null;
     },
 
-    /** Iterates through the available renderer implementations and selects 
-     *  and assigns the first one whose "supported()" function returns true.
-     * 
-     * @private
-     * 
+    /** 
+     * Method: assignRenderer
+     * Iterates through the available renderer implementations and selects 
+     * and assigns the first one whose "supported()" function returns true.
      */    
     assignRenderer: function()  {
         for (var i = 0; i < this.renderers.length; i++) {
@@ -125,10 +161,8 @@ OpenLayers.Layer.Vector.prototype =
     },
 
     /** 
+     * Method: displayError 
      * Let the user know their browser isn't supported.
-     * 
-     * @private
-     * 
      */
     displayError: function() {
         if (this.reportError) {
@@ -139,12 +173,15 @@ OpenLayers.Layer.Vector.prototype =
         }    
     },
 
-    /** The layer has been added to the map. 
+    /** 
+     * Method: setMap
+     * The layer has been added to the map. 
      * 
-     *  If there is no renderer set, the layer can't be used. Remove it.
-     *  Otherwise, give the renderer a reference to the map and set its size.
+     * If there is no renderer set, the layer can't be used. Remove it.
+     * Otherwise, give the renderer a reference to the map and set its size.
      * 
-     * @param {OpenLayers.Map} map
+     * Parameters:
+     * map - {<OpenLayers.Map>} 
      */
     setMap: function(map) {        
         OpenLayers.Layer.prototype.setMap.apply(this, arguments);
@@ -157,7 +194,9 @@ OpenLayers.Layer.Vector.prototype =
         }
     },
     
-    /** Notify the renderer of the change in size. 
+    /**
+     * Method: onMapResize
+     * Notify the renderer of the change in size. 
      * 
      */
     onMapResize: function() {
@@ -165,7 +204,9 @@ OpenLayers.Layer.Vector.prototype =
         this.renderer.setSize(this.map.getSize());
     },
 
-    /** Reset the vector layer's div so that it once again is lined up with 
+    /**
+     * Method: moveTo
+     *  Reset the vector layer's div so that it once again is lined up with 
      *   the map. Notify the renderer of the change of extent, and in the
      *   case of a change of zoom level (resolution), have the 
      *   renderer redraw features.
@@ -173,9 +214,10 @@ OpenLayers.Layer.Vector.prototype =
      *  If the layer has not yet been drawn, cycle through the layer's 
      *   features and draw each one.
      * 
-     * @param {OpenLayers.Bounds} bounds
-     * @param {Boolean} zoomChanged
-     * @param {Boolean} dragging
+     * Parameters:
+     * bounds - {<OpenLayers.Bounds>} 
+     * zoomChanged - {Boolean} 
+     * dragging - {Boolean} 
      */
     moveTo: function(bounds, zoomChanged, dragging) {
         OpenLayers.Layer.prototype.moveTo.apply(this, arguments);
@@ -197,7 +239,11 @@ OpenLayers.Layer.Vector.prototype =
     },
 
     /**
-     * @param {Array(OpenLayers.Feature.Vector} features
+     * APIMethod: addFeatures
+     * Add Features to the layer.
+     *
+     * Parameters:
+     * features - {Array(<OpenLayers.Feature.Vector>)} 
      */
     addFeatures: function(features) {
         if (!(features instanceof Array)) {
@@ -235,7 +281,10 @@ OpenLayers.Layer.Vector.prototype =
 
 
     /**
-     * @param {Array(OpenLayers.Feature.Vector} features
+     * APIMethod: removeFeatures
+     * 
+     * Parameters:
+     * features - {Array(<OpenLayers.Feature.Vector>)} 
      */
     removeFeatures: function(features) {
         if (!(features instanceof Array)) {
@@ -259,6 +308,7 @@ OpenLayers.Layer.Vector.prototype =
     },
 
     /**
+     * APIMethod: destroyFeatures
      * Destroy all features on the layer and empty the selected features array.
      */
     destroyFeatures: function () {
@@ -269,13 +319,15 @@ OpenLayers.Layer.Vector.prototype =
     },
 
     /**
+     * Method: drawFeature
      * Draw (or redraw) a feature on the layer.  If the optional style argument
      * is included, this style will be used.  If no style is included, the
      * feature's style will be used.  If the feature doesn't have a style,
      * the layer's style will be used.
      * 
-     * @param {OpenLayers.Feature.Vector} feature
-     * @param {Object} style
+     * Parameters: 
+     * feature - {<OpenLayers.Feature.Vector>} 
+     * style - {Object} 
      */
     drawFeature: function(feature, style) {
         if(style == null) {
@@ -289,21 +341,26 @@ OpenLayers.Layer.Vector.prototype =
     },
     
     /**
+     * Method: eraseFeatures
      * Erase features from the layer.
-     * 
-     * @param {Array(OpenLayers.Feature.Vector)} features
+     *
+     * Parameters:
+     * features - {Array(OpenLayers.Feature.Vector)} 
      */
     eraseFeatures: function(features) {
         this.renderer.eraseFeatures(features);
     },
 
     /**
+     * Method: getFeatureFromEvent
      * Given an event, return a feature if the event occurred over one.
      * Otherwise, return null.
      *
-     * @param {Event}
-     * @type OpenLayers.Feature.Vector
-     * @return A feature if one was under the event
+     * Parameters:
+     * evt - {Event} 
+     *
+     * Returns:
+     * {<OpenLayers.Feature.Vector>} A feature if one was under the event.
      */
     getFeatureFromEvent: function(evt) {
         var featureId = this.renderer.getFeatureIdFromEvent(evt);
@@ -311,11 +368,15 @@ OpenLayers.Layer.Vector.prototype =
     },
     
     /**
+     * APIMethod: getFeatureById
      * Given a feature id, return the feature if it exists in the features array
-     * 
-     * @param {String} featureId
-     * @type OpenLayers.Feature.Vector
-     * @return A feature corresponding to the given featureId
+     *
+     * Parameters:
+     * featureId - {String} 
+     *
+     * Returns:
+     * {<OpenLayers.Feature.Vector>} A feature corresponding to the given
+     * featureId
      */
     getFeatureById: function(featureId) {
         //TBD - would it be more efficient to use a hash for this.features?
@@ -346,26 +407,33 @@ OpenLayers.Layer.Vector.prototype =
 
 
     /**
-     * method called when a feature is inserted.
+     * APIMethod: onFeatureInsert
+     * method called after a feature is inserted.
      * Does nothing by default. Override this if you
      * need to do something on feature updates.
-     * 
-     * @param {OpenLayers.Feature.Vector} feature
+     *
+     * Paarameters: 
+     * feature - {<OpenLayers.Feature.Vector>} 
      */
     onFeatureInsert: function(feature) {
     },
     
     /**
+     * APIMethod: preFeatureInsert
      * method called before a feature is inserted.
      * Does nothing by default. Override this if you
      * need to do something when features are first added to the
      * layer, but before they are drawn, such as adjust the style.
-     * 
-     * @param {OpenLayers.Feature.Vector} feature
+     *
+     * Parameters:
+     * feature - {<OpenLayers.Feature.Vector>} 
      */
     preFeatureInsert: function(feature) {
     },
 
-    /** @final @type String */
+    /**
+     * Constant: CLASS_NAME
+     * {String} 'OpenLayers.Layer.Vector'
+     */
     CLASS_NAME: "OpenLayers.Layer.Vector"
 });