From be09368359408a7fb788734aac1bd7a4fa958601 Mon Sep 17 00:00:00 2001
From: Peter Robins <github@peterrobins.co.uk>
Date: Sat, 12 Jul 2014 19:58:40 +0000
Subject: [PATCH] Document map DOM elements

---
 externs/olx.js            | 3 ++-
 src/ol/control/control.js | 5 +++--
 src/ol/map.js             | 9 +++++++++
 3 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/externs/olx.js b/externs/olx.js
index 87777ba3c3..ba66e8c77b 100644
--- a/externs/olx.js
+++ b/externs/olx.js
@@ -258,7 +258,8 @@ olx.OverlayOptions.prototype.positioning;
 /**
  * Whether event propagation to the map viewport should be stopped. Default is
  * `true`. If `true` the overlay is placed in the same container as that of the
- * controls (`ol-overlaycontainer-stopevent`).
+ * controls (CSS class name `ol-overlaycontainer-stopevent`); if `false` it is
+ * placed in the container with CSS class name `ol-overlaycontainer`.
  * @type {boolean|undefined}
  */
 olx.OverlayOptions.prototype.stopEvent;
diff --git a/src/ol/control/control.js b/src/ol/control/control.js
index 6d890dbf7f..1d63b0f74c 100644
--- a/src/ol/control/control.js
+++ b/src/ol/control/control.js
@@ -12,8 +12,9 @@ goog.require('ol.Object');
  * @classdesc
  * A control is a visible widget with a DOM element in a fixed position on the
  * screen. They can involve user input (buttons), or be informational only;
- * the position is determined using CSS. By default these are part of the map
- * container, but can use any outside DOM element.
+ * the position is determined using CSS. By default these are placed in the
+ * container with CSS class name `ol-overlaycontainer-stopevent`, but can use
+ * any outside DOM element.
  *
  * This is the base class for controls. You can use it for simple custom
  * controls by creating the element with listeners, creating an instance:
diff --git a/src/ol/map.js b/src/ol/map.js
index a3038d77fb..bac8302ec9 100644
--- a/src/ol/map.js
+++ b/src/ol/map.js
@@ -139,6 +139,15 @@ ol.MapProperty = {
  * The above snippet creates a map with a MapQuest OSM layer on a 2D view and
  * renders it to a DOM element with the id `map`.
  *
+ * The constructor places a viewport container (with CSS class name
+ * `ol-viewport`) in the target element (see `getViewport()`), and then two
+ * further elements within the viewport: one with CSS class name
+ * `ol-overlaycontainer-stopevent` for controls and some overlays, and one with
+ * CSS class name `ol-overlaycontainer` for other overlays (see the `stopEvent`
+ * option of {@link ol.Overlay} for the difference). The map itself is placed in
+ * a further element within the viewport, either DOM or Canvas, depending on the
+ * renderer.
+ *
  * @constructor
  * @extends {ol.Object}
  * @param {olx.MapOptions} options Map options.