Improvements for projection docs

lib/OpenLayers/Layer.js

@@ -191,18 +191,32 @@ OpenLayers.Layer = OpenLayers.Class({
 
     /**
      * APIProperty: projection
-     * {<OpenLayers.Projection>} or {<String>} Set in the layer options to
+     * {<OpenLayers.Projection>} or {<String>} Specifies the projection of the layer.
-     *     override the default projection string this layer - also set maxExtent,
+     *     Can be set in the layer options. If not specified in the layer options,
-     *     maxResolution, and units if appropriate. Can be either a string or
+     *     it is set to the default projection specified in the map,
-     *     an <OpenLayers.Projection> object when created -- will be converted
+     *     when the layer is added to the map.
-     *     to an object when setMap is called if a string is passed.  
+     *     Projection along with default maxExtent and resolutions
+     *     are set automatically with commercial baselayers in EPSG:3857,
+     *     such as Google, Bing and OpenStreetMap, and do not need to be specified.
+     *     Otherwise, if specifying projection, also set maxExtent,
+     *     maxResolution or resolutions as appropriate.
+     *     When using vector layers with strategies, layer projection should be set
+     *     to the projection of the source data if that is different from the map default.
+     * 
+     *     Can be either a string or an <OpenLayers.Projection> object;
+     *     if a string is passed, will be converted to an object when
+     *     the layer is added to the map.
+     * 
      */
     projection: null,    
     
     /**
      * APIProperty: units
-     * {String} The layer map units.  Defaults to 'degrees'.  Possible values
+     * {String} The layer map units.  Defaults to null.  Possible values
      *     are 'degrees' (or 'dd'), 'm', 'ft', 'km', 'mi', 'inches'.
+     *     Normally taken from the projection.
+     *     Only required if both map and layers do not define a projection,
+     *     or if they define a projection which does not define units.
      */
     units: null,
 

lib/OpenLayers/Map.js

@@ -256,18 +256,21 @@ OpenLayers.Map = OpenLayers.Class({
 
     /**
      * APIProperty: projection
-     * {String} Set in the map options to override the default projection 
+     * {String} Set in the map options to specify the default projection 
-     *          string this map. When using a projection other than EPSG:4326
+     *          for layers added to this map. When using a projection other than EPSG:4326
      *          (CRS:84, Geographic) or EPSG:3857 (EPSG:900913, Web Mercator),
-     *          also set maxExtent and maxResolution.  Default is "EPSG:4326".
+     *          also set maxExtent, maxResolution or resolutions.  Default is "EPSG:4326".
+     *          Note that the projection of the map is usually determined
+     *          by that of the current baseLayer (see <baseLayer> and <getProjectionObject>).
      */
     projection: "EPSG:4326",    
         
     /**
      * APIProperty: units
      * {String} The map units.  Possible values are 'degrees' (or 'dd'), 'm', 
-     *     'ft', 'km', 'mi', 'inches'.  Only required if the projection default
+     *     'ft', 'km', 'mi', 'inches'.  Normally taken from the projection.
-     *     should be overridden.
+     *     Only required if both map and layers do not define a projection,
+     *     or if they define a projection which does not define units
      */
     units: null,
 

lib/OpenLayers/Projection.js

@@ -54,7 +54,7 @@ OpenLayers.Projection = OpenLayers.Class({
      * projCode - {String} A string identifying the Well Known Identifier for
      *    the projection.
      * options - {Object} An optional object to set additional properties
-     *     on the layer.
+     *     on the projection.
      *
      * Returns:
      * {<OpenLayers.Projection>} A projection object.