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

@@ -3,26 +3,50 @@
  * for the full text of the license. */
 // @requires OpenLayers/Layer/Grid.js
 /**
-* @class
  * @requires OpenLayers/Layer/Grid.js
-*/
+ *
+ * Class: OpenLayers.Layer.MapServer
+ * Instances of OpenLayers.Layer.MapServer are used to display
+ * data from a MapServer CGI instance.
+ *
+ * Inherits from:
+ *  - <OpenLayers.Layer.Grid>
+ */
 OpenLayers.Layer.MapServer = OpenLayers.Class.create();
 OpenLayers.Layer.MapServer.prototype =
   OpenLayers.Class.inherit( OpenLayers.Layer.Grid, {
 
-    /** @final @type hash */
+      /**
+       * Constant: DEFAULT_PARAMS
+       * {Object} Hashtable of default parameter key/value pairs 
+       */
     DEFAULT_PARAMS: {
                       mode: "map",
                       map_imagetype: "png"
                      },
 
-    /**
-    * @constructor
-    *
-    * @param {str} name
-    * @param {str} url
-    * @param {hash} params
-    */
+     /**
+      * Constructor: OpenLayers.Layer.MapServer
+      * Create a new MapServer layer object
+      *
+      * Example:
+      * (code)
+      * layer = new OpenLayers.Layer.MapServer( "OpenLayers WMS", 
+      *         "http://labs.metacarta.com/wms/vmap0", {layers: 'basic'},
+      *         {gutter: 15});
+      * (end)
+      *
+      * Parameters:
+      * name - {String} A name for the layer
+      * url - {String} Base url for the MapServer CGI
+      *       (e.g. http://www2.dmsolutions.ca/cgi-bin/mapserv)
+      * params - {Object} An object with key/value pairs representing the
+      *          GetMap query string parameters and parameter values.
+      * options - {Ojbect} Hashtable of extra options to tag onto the layer
+      *
+      * Return:
+      * A new OpenLayers.Layer.MapServer instance
+      */
     initialize: function(name, url, params, options) {
         var newArguments = new Array();
         newArguments.push(name, url, params, options);
@@ -44,11 +68,12 @@ OpenLayers.Layer.MapServer.prototype =
     },
 
     /**
-    * @param {Object} obj
-    *
-    * @returns A clone of this OpenLayers.Layer.MapServer
-    * @type OpenLayers.Layer.MapServer
-    */
+     * Method: clone
+     * Create a clone of this layer
+     *
+     * Return:
+     * {<OpenLayers.Layer.MapServer>} An exact clone of this layer
+     */
     clone: function (obj) {
         if (obj == null) {
             obj = new OpenLayers.Layer.MapServer(this.name,
@@ -65,10 +90,10 @@ OpenLayers.Layer.MapServer.prototype =
     },
 
     /**
-    * addTile creates a tile, initializes it (via 'draw' in this case), and
-    * adds it to the layer div.
+    * addTile creates a tile, initializes it, and 
+    * adds it to the layer div. 
     *
-    * @param {OpenLayers.Bounds} bounds
+    * @param {<OpenLayers.Bounds>} bounds
     *
     * @returns The added OpenLayers.Tile.Image
     * @type OpenLayers.Tile.Image
@@ -79,12 +104,16 @@ OpenLayers.Layer.MapServer.prototype =
     },
     
     /**
-     * @param {OpenLayers.Bounds} bounds
-     * 
-     * @returns A string with the layer's url and parameters and also the 
-     *           passed-in bounds and appropriate tile size specified as 
-     *           parameters
-     * @type String
+     * Method: getURL
+     * Return a query string for this layer
+     *
+     * Parameters:
+     * bounds - {<OpenLayers.Bounds>} A bounds representing the bbox for the
+     *          request
+     *
+     * Return:
+     * {String} A string with the layer's url and parameters and also the
+     * passed-in bounds and appropriate tile size specified as parameters
      */
     getURL: function (bounds) {
         bounds = this.adjustBounds(bounds);
@@ -105,17 +134,20 @@ OpenLayers.Layer.MapServer.prototype =
     },
     
     /** 
-     * getFullRequestString on MapServer layers is special, because we 
-     * do a regular expression replace on ',' in parameters to '+'.
-     * This is why it is subclassed here.
-     *
-     * @param {Object} newParams Parameters to add to the default parameters
-     *                           for the layer.
-     * @param {String} altUrl    Alternative base URL to use.
-     */
+    * Method: getFullRequestString
+    * combine the layer's url with its params and these newParams. 
+    *   
+    * Parameter: {Object} newParams
+    * new parameters that should be added to the request string.
+    * 
+    * Parameter: {String} altUrl
+    * optional, replace the URL in the full request string with the
+    * provided URL.
+    * 
+    * Return: {String}
+    * A string with the layer's url and parameters embedded in it.
+    */
     getFullRequestString:function(newParams, altUrl) {
-        
-    
         // use layer's url unless altUrl passed in
         var url = (altUrl == null) ? this.url : altUrl;
         
@@ -166,6 +198,9 @@ OpenLayers.Layer.MapServer.prototype =
         }
         return requestString;
     },
-    /** @final @type String */
+    /**
+     * Constant: CLASS_NAME
+     * {String} OpenLayers.Layer.MapServer
+     */
     CLASS_NAME: "OpenLayers.Layer.MapServer"
 });