Merge pull request openlayers#476 from probins/googledoc

Document issues with Google v3 layers

lib/OpenLayers/Layer/EventPane.js

@@ -11,7 +11,13 @@
 
 /**
  * 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.
+ * Only used by Google layers.
+ *
+ * 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,42 @@
 /**
  * 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.
+ * These elements are not part of the published API and can be changed at any time,
+ * so a given OpenLayers release can only guarantee support for the 'frozen'
+ * Google release at the time of the OpenLayers 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, however, that frozen versions are retired as part of Google's release
+ * cycle, and once this happens, you will get the next version, in the example above, 3.8 once 3.7 is retired.
+ * 
+ * This version supports 3.7.
+ * 
+ * 
+ * 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 = {
 

notes/2.12.md

@@ -219,6 +219,20 @@ Corresponding issues/pull requests:
 
  * https://github.com/openlayers/openlayers/pull/101
 
+## Google v3 Layer
+
+This release fixes a problem with the clickable elements supplied by Google. `OpenLayers.Layer.Google.v3` is now compatible with the current frozen version of Google's API (3.7) and also with the current release and nightly versions (3.8 and 3.9), but be aware that Google may change these elements in their release and nightly versions at any time, and an interim fix OpenLayers release may be needed.
+
+It's recommended that production servers always load the frozen version of Google's API, but it would help find potential problems if development pages used the latest nightly version.
+
+See the class description in the API docs for `OpenLayers.Layer.Google.v3` for more details.
+
+Good ideas on how to improve this unsatisfactory situation welcome!
+
+Corresponding issues/pull requests:
+
+ * https://github.com/openlayers/openlayers/pull/472
+
 ## OSM and Bing Layers
 
 `Layer.OSM` is now defined in its own script file, namely `OpenLayers/Layer/OSM.js`. So people using `Layer.OSM` should now include `OpenLayers/Layer/OSM.js`, as opposed to `OpenLayers/Layer/XYZ.js`, in their OpenLayers builds.