Some comments (no changes to code)

src/ol/map.js

@@ -80,7 +80,8 @@ ol.RendererHint = {
 
 
 /**
- * @type {Array.<ol.RendererHint>}
+ * @type {Array.<ol.RendererHint>} Desired renderers with most favoured renderer
+ *   first.
  */
 ol.DEFAULT_RENDERER_HINTS = [
   ol.RendererHint.WEBGL,
@@ -113,6 +114,9 @@ ol.MapProperty = {
 
 
 /**
+ * Map composed of multiple layers. Maps in OpenLayers are responsible for
+ * binding together the other components.
+ *
  * @constructor
  * @extends {ol.Object}
  * @implements {goog.fx.anim.Animated}
@@ -170,7 +174,7 @@ ol.Map = function(mapOptions) {
 
   /**
    * @private
-   * @type {Element}
+   * @type {Element} Container into which the map is painted.
    */
   this.target_ = mapOptionsInternal.target;
 
@@ -182,7 +186,7 @@ ol.Map = function(mapOptions) {
 
   /**
    * @private
-   * @type {Element}
+   * @type {Element} Reference to the root element of the map in the DOM.
    */
   this.viewport_ = goog.dom.createDom(goog.dom.TagName.DIV, 'ol-viewport');
   this.viewport_.style.position = 'relative';
@@ -193,7 +197,8 @@ ol.Map = function(mapOptions) {
 
   /**
    * @private
-   * @type {Element}
+   * @type {Element} Captures click events and cancels them so that interactions
+   *   within overlays don't influence the map.
    */
   this.overlayContainer_ = goog.dom.createDom(goog.dom.TagName.DIV,
       'ol-overlaycontainer');
@@ -244,7 +249,8 @@ ol.Map = function(mapOptions) {
   this.interactions_ = mapOptionsInternal.interactions;
 
   /**
-   * @type {ol.renderer.Map}
+   * @type {ol.renderer.Map} Most favoured renderer given the supported of the
+   *   choices.
    * @private
    */
   this.renderer_ =
@@ -271,6 +277,7 @@ ol.Map = function(mapOptions) {
 
   this.handleBrowserWindowResize();
 
+  // Notify all controls about the map they are assigned to
   this.controls_.forEach(
       /**
        * @param {ol.control.Control} control Control.
@@ -292,7 +299,6 @@ ol.Map.prototype.canRotate = function() {
 
 
 /**
- *
  * @inheritDoc
  */
 ol.Map.prototype.disposeInternal = function() {
@@ -359,7 +365,7 @@ goog.exportProperty(
 
 
 /**
- * @return {Element} Container.
+ * @return {Element} Container into which the map is painted.
  */
 ol.Map.prototype.getTarget = function() {
   return this.target_;
@@ -644,6 +650,10 @@ ol.Map.prototype.handleUserProjectionChanged = function() {
 
 
 /**
+ * Adjusts the map to its new size whenever the viewport size changes.
+ * One should react the the resize of the map's viewport instead of the browser
+ * viewport but there is no API to do so.
+ *
  * @protected
  */
 ol.Map.prototype.handleBrowserWindowResize = function() {
@@ -1003,10 +1013,16 @@ ol.Map.createOptionsInternal = function(mapOptions) {
    */
   var rendererHints;
   if (goog.isDef(mapOptions.renderers)) {
+    // Use first supported renderer of the supported ones
     rendererHints = mapOptions.renderers;
   } else if (goog.isDef(mapOptions.renderer)) {
+    // Use the given renderer
+    // Support accepting a renderer instead of an array with a single renderer
+    // for mapOptions.renderers.
     rendererHints = [mapOptions.renderer];
   } else {
+    // Use the default order of preferred renderers if user did not specify a
+    // preference.
     rendererHints = ol.DEFAULT_RENDERER_HINTS;
   }
 
@@ -1052,7 +1068,7 @@ ol.Map.createOptionsInternal = function(mapOptions) {
   }
 
   /**
-   * @type {Element}
+   * @type {Element} Container into which the map is painted.
    */
   var target = goog.dom.getElement(mapOptions.target);