better documentation for Layer.WMS

git-svn-id: http://svn.openlayers.org/trunk/openlayers@12144 dc9f47b5-9b13-0410-9fdd-eb0c1a62fdaf

lib/OpenLayers/Layer/WMS.js

@@ -76,12 +76,37 @@ OpenLayers.Layer.WMS = OpenLayers.Class(OpenLayers.Layer.Grid, {
      * Constructor: OpenLayers.Layer.WMS
      * Create a new WMS layer object
      *
-     * Example:
+     * Examples:
+     *
+     * This code creates a simple WMS layer using the image/jpeg format:
      * (code)
      * var wms = new OpenLayers.Layer.WMS("NASA Global Mosaic",
      *                                    "http://wms.jpl.nasa.gov/wms.cgi", 
      *                                    {layers: "modis,global_mosaic"});
      * (end)
+     * Note the 3rd argument (params). Properties added to this object will be
+     * added to the WMS GetMap requests used for this layer's tiles. The only
+     * mandatory parameter is "layers". Other common WMS params include
+     * "transparent", "styles" and "format". Note that the "srs" param will
+     * always be ignored. Instead, it will be derived from the baseLayer's or
+     * map's projection.
+     *
+     * This code creates a transparent WMS layer with additional options:
+     * (code)
+     * var wms = new OpenLayers.Layer.WMS("NASA Global Mosaic",
+     *                                    "http://wms.jpl.nasa.gov/wms.cgi", 
+     *                                    {
+     *                                        layers: "modis,global_mosaic",
+     *                                        transparent: true
+     *                                    }, {
+     *                                        opacity: 0.5,
+     *                                        singleTile: true
+     *                                    });
+     * (end)
+     * Note that by default, a WMS layer is configured as baseLayer. Setting
+     * the "transparent" param to true will apply some magic (see <noMagic>).
+     * The default image format changes from image/jpeg to image/png, and the
+     * layer is not configured as baseLayer.
      *
      * Parameters:
      * name - {String} A name for the layer
@@ -89,7 +114,9 @@ OpenLayers.Layer.WMS = OpenLayers.Class(OpenLayers.Layer.Grid, {
      *                (e.g. http://wms.jpl.nasa.gov/wms.cgi)
      * 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
+     * options - {Ojbect} Hashtable of extra options to tag onto the layer.
+     *     These options include all properties listed above, plus the ones
+     *     inherited from superclasses.
      */
     initialize: function(name, url, params, options) {
         var newArguments = [];