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

@@ -4,47 +4,54 @@
 
 
 /**
- * @class
- * 
  * @requires OpenLayers/Layer.js
+ * 
+ * Class: OpenLayers.Layer.HTTPRequest
+ * 
+ * Inherits: 
+ *  - OpenLayers.Layer
  */
 OpenLayers.Layer.HTTPRequest = OpenLayers.Class.create();
 OpenLayers.Layer.HTTPRequest.prototype = 
   OpenLayers.Class.inherit( OpenLayers.Layer, {
 
-    /** Used to hash URL param strings for multi-WMS server selection.
-     * Set to the Golden Ratio per Knuth's recommendation.
-     *
-     * @final @type Numeric
+    /** 
+     * Constant: URL_HASH_FACTOR
+     * {Float} Used to hash URL param strings for multi-WMS server selection.
+     *         Set to the Golden Ratio per Knuth's recommendation.
      */
     URL_HASH_FACTOR: (Math.sqrt(5) - 1) / 2,
 
-    /** This is either an array of url strings or a single url string. 
-     * 
-     * @type Array(String) or String */
+    /** 
+     * Property: url
+     * {Array(String) or String} This is either an array of url strings or 
+     *                           a single url string. 
+     */
     url: null,
 
-    /** Hashtable of key/value parameters
-     * 
-     * @type Object */
+    /** 
+     * Property: params
+     * {Object} Hashtable of key/value parameters
+     */
     params: null,
     
-    /** Whether layer should reproject itself based on base layer locations.
-     *  This allows reprojection onto commercial layers. Default is false:
-     *  Most layers can't reproject, but layers which can create non-square
-     *  geographic pixels can, like WMS. 
-     *
-     * @type Boolean 
+    /** 
+     * APIProperty: reproject
+     * {Boolean} Whether layer should reproject itself based on base layer 
+     *           locations. This allows reprojection onto commercial layers. 
+     *           Default is false: Most layers can't reproject, but layers 
+     *           which can create non-square geographic pixels can, like WMS. 
      */
     reproject: false,
 
     /**
-     * @constructor
+     * Constructor: OpenLayers.Layer.HTTPRequest
      * 
-     * @param {String} name
-     * @param {Array(String) or String} url
-     * @param {Object} params
-     * @param {Object} options Hashtable of extra options to tag onto the layer
+     * Parameters:
+     * name - {String}
+     * url - {Array(String) or String}
+     * params - {Object}
+     * options - {Object} Hashtable of extra options to tag onto the layer
      */
     initialize: function(name, url, params, options) {
         var newArguments = arguments;
@@ -55,7 +62,7 @@ OpenLayers.Layer.HTTPRequest.prototype =
     },
 
     /**
-     * 
+     * APIMethod: destroy
      */
     destroy: function() {
         this.url = null;
@@ -64,10 +71,14 @@ OpenLayers.Layer.HTTPRequest.prototype =
     },
     
     /**
-     * @param {Object} obj
+     * APIMethod: clone
      * 
-     * @returns An exact clone of this OpenLayers.Layer.HTTPRequest
-     * @type OpenLayers.Layer.HTTPRequest
+     * Parameters:
+     * obj - {Object}
+     * 
+     * Return:
+     * {<OpenLayers.Layer.HTTPRequest>} An exact clone of this 
+     *                                  <OpenLayers.Layer.HTTPRequest>
      */
     clone: function (obj) {
         
@@ -87,33 +98,40 @@ OpenLayers.Layer.HTTPRequest.prototype =
     },
 
     /** 
-     * @param {String} newUrl
+     * APIMethod: setUrl
+     * 
+     * Parameters:
+     * newUrl - {String}
      */
     setUrl: function(newUrl) {
         this.url = newUrl;
     },
 
     /**
-     * @param {Object} newParams
+     * APIMethod: mergeNewParams
+     * 
+     * Parameters:
+     * newParams - {Object}
      */
     mergeNewParams:function(newParams) {
         this.params = OpenLayers.Util.extend(this.params, newParams);
     },
     
     /**
+     * Method: selectUrl
      * selectUrl() implements the standard floating-point multiplicative
-     * hash function described by Knuth, and hashes the contents of the 
-     * given param string into a float between 0 and 1. This float is then
-     * scaled to the size of the provided urls array, and used to select
-     * a URL.
+     *     hash function described by Knuth, and hashes the contents of the 
+     *     given param string into a float between 0 and 1. This float is then
+     *     scaled to the size of the provided urls array, and used to select
+     *     a URL.
      *
-     * @param {String} paramString
-     * @param {Array(String)} urls
-     * 
-     * @returns An entry from the urls array, deterministically selected based
-     *           on the paramString.
-     * @type String
+     * Parameters:
+     * paramString - {String}
+     * urls - {Array(String)}
      * 
+     * Return:
+     * {String} An entry from the urls array, deterministically selected based
+     *          on the paramString.
      */
     selectUrl: function(paramString, urls) {
         var product = 1;
@@ -124,7 +142,9 @@ OpenLayers.Layer.HTTPRequest.prototype =
         return urls[Math.floor(product * urls.length)];
     },
 
-    /** combine url with layer's params and these newParams. 
+    /** 
+     * Method: getFullRequestString
+     * Combine url with layer's params and these newParams. 
      *   
      *    does checking on the serverPath variable, allowing for cases when it 
      *     is supplied with trailing ? or &, as well as cases where not. 
@@ -134,11 +154,12 @@ OpenLayers.Layer.HTTPRequest.prototype =
      * 
      * WARNING: The altUrl parameter is deprecated and will be removed in 3.0.
      *
-     * @param {Object} newParams
-     * @param {String} altUrl Use this as the url instead of the layer's url
+     * Parameters:
+     * newParams - {Object}
+     * altUrl - {String} Use this as the url instead of the layer's url
      *   
-     * 
-     * @type String
+     * Return: 
+     * {String}
      */
     getFullRequestString:function(newParams, altUrl) {