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/Tile/WFS.js

@@ -4,40 +4,55 @@
 
  
 /**
- * @class
- * 
  * @requires OpenLayers/Tile.js
+ * 
+ * Class: OpenLayers.Tile.WFS
+ * Instances of OpenLayers.Tile.WFS are used to manage the image tiles
+ * used by various layers.  Create a new image tile with the
+ * <OpenLayers.Tile.WFS> constructor.
+ *
+ * Inherits from:
+ *  - <OpenLayers.Tile>
  */
 OpenLayers.Tile.WFS = OpenLayers.Class.create();
 OpenLayers.Tile.WFS.prototype = 
   OpenLayers.Class.inherit( OpenLayers.Tile, {
 
-    /** @type Array(OpenLayers.Feature)*/ 
-    features: null,
+    /** 
+	 * Property: features 
+	 * {Array(<OpenLayers.Feature>)} list of features in this tile 
+	 */
+	features: null,
 
-    /** @type Array(String) */
-    url: null,
+    /** 
+	 * Property: url 
+	 * {String} 
+	 */
+	url: null,
     
     /** TBD 3.0 - reorder the parameters to the init function to put URL 
      *             as last, so we can continue to call tile.initialize() 
      *             without changing the arguments. 
      * 
-    * @constructor
-    *
-    * @param {OpenLayers.Layer} layer
-    * @param {OpenLayers.Pixel} position
-    * @param {OpenLayers.Bounds} bounds
-    * @param {String} url
-    * @param {OpenLayers.Size} size
-    */
+     * Constructor: OpenLayers.Tile.WFS
+     * Constructor for a new <OpenLayers.Tile.WFS> instance.
+     * 
+     * Parameters:
+     * layer - {<OpenLayers.Layer>} layer that the tile will go in.
+     * position - {<OpenLayers.Pixel>}
+     * bounds - {<OpenLayers.Bounds>}
+     * url - {<String>}
+     * size - {<OpenLayers.Size>}
+     */   
     initialize: function(layer, position, bounds, url, size) {
         OpenLayers.Tile.prototype.initialize.apply(this, arguments);
         this.url = url;        
         this.features = new Array();
     },
 
-    /**
-     * 
+    /** 
+     * APIMethod: destroy
+     * nullify references to prevent circular references and memory leaks
      */
     destroy: function() {
         OpenLayers.Tile.prototype.destroy.apply(this, arguments);
@@ -46,7 +61,9 @@ OpenLayers.Tile.WFS.prototype =
         this.url = null;
     },
 
-    /** Clear the tile of any bounds/position-related data so that it can 
+    /** 
+     * Method: clear
+     *  Clear the tile of any bounds/position-related data so that it can 
      *   be reused in a new location.
      */
     clear: function() {
@@ -55,7 +72,8 @@ OpenLayers.Tile.WFS.prototype =
     },
     
     /**
-     * 
+     * Method: draw
+     * Check that a tile should be drawn, and load features for it.
      */
     draw:function() {
         if (OpenLayers.Tile.prototype.draw.apply(this, arguments)) {
@@ -63,21 +81,28 @@ OpenLayers.Tile.WFS.prototype =
         }
     },
 
-    /** get the full request string from the ds and the tile params 
+    /** 
+    * Method: loadFeaturesForRegion
+    * get the full request string from the ds and the tile params 
     *     and call the AJAX loadURL(). 
     *
-    *     input are function pointers for what to do on success and failure.
-    * 
-    * @param {function} success
-    * @param {function} failure
+    * Input are function pointers for what to do on success and failure.
+    *
+    * Parameters:
+    * success - {function}
+    * failure - {function}
     */
     loadFeaturesForRegion:function(success, failure) {
         OpenLayers.loadURL(this.url, null, this, success);
     },
     
-    /** Return from AJAX request
+    /**
+    * Method: requestSuccess
+    * Called on return from request succcess. Adds results via 
+    * layer.addFeatures in vector mode, addResults otherwise. 
     *
-    * @param {} request
+    * Parameters:
+    * request - {XMLHttpRequest}
     */
     requestSuccess:function(request) {
         var doc = request.responseXML;
@@ -95,7 +120,12 @@ OpenLayers.Tile.WFS.prototype =
     },
 
     /**
-     * @param {Object} results
+     * Method: addResults
+     * Construct new feature via layer featureClass constructor, and add to
+     * this.features.
+     * 
+     * Parameters:
+     * results - {Object}
      */
     addResults: function(results) {
         for (var i=0; i < results.length; i++) {
@@ -106,10 +136,10 @@ OpenLayers.Tile.WFS.prototype =
     },
 
 
-    /** Iterate through and call destroy() on each feature, removing it from
+    /** 
+     * Method: destroyAllFeatures
+     * Iterate through and call destroy() on each feature, removing it from
      *   the local array
-     * 
-     * @private
      */
     destroyAllFeatures: function() {
         while(this.features.length > 0) {
@@ -118,7 +148,10 @@ OpenLayers.Tile.WFS.prototype =
         }
     },
     
-    /** @final @type String */
+    /**
+     * Constant: CLASS_NAME
+     * {String} Name of class.
+     */
     CLASS_NAME: "OpenLayers.Tile.WFS"
   }
 );