Document issues with Google v3 layers

lib/OpenLayers/Layer/EventPane.js

@@ -11,7 +11,14 @@
 
 /**
  * Class: OpenLayers.Layer.EventPane
- * Base class for 3rd party layers.  Create a new event pane layer with the
+ * Base class for 3rd party layers, providing a DOM element which isolates
+ * the 3rd-party layer from mouse events.
+ * Originally used by Yahoo, Virtual Earth and Google layers, but now
+ * only used by Google.
+ *
+ * Automatically instantiated by the Google constructor, and not usually instantiated directly.
+ *
+ * Create a new event pane layer with the
  * <OpenLayers.Layer.EventPane> constructor.
  * 
  * Inherits from:

lib/OpenLayers/Layer/Google.js

@@ -14,6 +14,11 @@
 /**
  * Class: OpenLayers.Layer.Google
  * 
+ * Provides a wrapper for Google's Maps API
+ * Normally the Terms of Use for this API do not allow wrapping, but Google
+ * have provided written consent to OpenLayers for this - see email in 
+ * http://osgeo-org.1560.n6.nabble.com/Google-Maps-API-Terms-of-Use-changes-tp4910013p4911981.html
+ * 
  * Inherits from:
  *  - <OpenLayers.Layer.SphericalMercator>
  *  - <OpenLayers.Layer.EventPane>
@@ -462,6 +467,10 @@ OpenLayers.Layer.Google.cache = {};
  * Constant: OpenLayers.Layer.Google.v2
  * 
  * Mixin providing functionality specific to the Google Maps API v2.
+ * 
+ * This API has been deprecated by Google.
+ * Developers are encouraged to migrate to v3 of the API; support for this
+ * is provided by <OpenLayers.Layer.Google.v3>
  */
 OpenLayers.Layer.Google.v2 = {
     

lib/OpenLayers/Layer/Google/v3.js

@@ -11,15 +11,33 @@
 /**
  * Constant: OpenLayers.Layer.Google.v3
  * 
- * Mixin providing functionality specific to the Google Maps API v3 <= v3.6.
- * Note that this layer configures the google.maps.map object with the
- * "disableDefaultUI" option set to true. Using UI controls that the Google
- * Maps API provides is not supported by the OpenLayers API. To use this layer,
- * you must include the GMaps API (<= v3.6) in your html:
+ * Mixin providing functionality specific to the Google Maps API v3.
+ * 
+ * To use this layer, you must include the GMaps v3 API in your html.
+ * Because OpenLayers needs to control mouse events, it isolates the GMaps mapObject
+ * (the DOM elements provided by Google) using the EventPane.
+ * However, because the Terms of Use require some of those elements,
+ * such as the links to Google's terms, to be clickable, these elements have 
+ * to be moved up to OpenLayers' container div. There is however no easy way
+ * to identify these, and the logic (see the repositionMapElements function
+ * in the source) may need to be changed if Google changes them.
+ * Because of this, a given OpenLayers release can only guarantee support for the current 'frozen' Google release
+ * (see https://developers.google.com/maps/documentation/javascript/basics#Versioning
+ * for Google's current release cycle).
+ * 
+ * For this reason, it's recommended that production code specifically loads 
+ * the current frozen version, for example:
  *
  * (code)
- * <script src="http://maps.google.com/maps/api/js?v=3.6&amp;sensor=false"></script>
+ * <script src="http://maps.google.com/maps/api/js?v=3.7&amp;sensor=false"></script>
  * (end)
+ * 
+ * but that development code should use the latest 'nightly' version, so that any
+ * problems can be dealt with as soon as they arise, and before they affect the production, 'frozen', code.
+ * 
+ * Note that this layer configures the google.maps.map object with the
+ * "disableDefaultUI" option set to true. Using UI controls that the Google
+ * Maps API provides is not supported by the OpenLayers API.
  */
 OpenLayers.Layer.Google.v3 = {