Merge pull request #2355 from probins/mapelements

Document map DOM elements

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;

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
+ * the position is determined using CSS. By default these are placed in the
- * container, but can use any outside DOM element.
+ * 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:

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.