Some comments (no changes to code)

src/ol/control/attributioncontrol.js

@@ -20,13 +20,19 @@ goog.require('ol.layer.Layer');
 
 
 /**
+ * Shows credits / names of data providers for shown map layers.
+ *
  * @constructor
  * @extends {ol.control.Control}
  * @param {ol.control.AttributionOptions} attributionOptions Attribution
  *     options.
  */
 ol.control.Attribution = function(attributionOptions) {
-
+  /**
+   * @private
+   * @type {Element} List of map's data sources. One list items gets appended
+   *   per data source.
+   */
   this.ulElement_ = goog.dom.createElement(goog.dom.TagName.UL);
 
   var element = goog.dom.createDom(goog.dom.TagName.DIV, {
@@ -35,7 +41,8 @@ ol.control.Attribution = function(attributionOptions) {
 
   /**
    * @private
-   * @type {Array.<number>}
+   * @type {Array.<number>} Event handler identifiers to change attribution when
+   *   layers get added and removed.
    */
   this.layersListenerKeys_ = null;
 
@@ -59,7 +66,8 @@ ol.control.Attribution = function(attributionOptions) {
 
   /**
    * @private
-   * @type {Array.<number>}
+   * @type {Array.<number>} Event handler identifiers for handlers that monitor
+   *   changes to the map.
    */
   this.mapListenerKeys_ = null;
 
@@ -74,6 +82,9 @@ goog.inherits(ol.control.Attribution, ol.control.Control);
 
 
 /**
+ * Attaches handler to track visibility changes and creates attribution list
+ * item.
+ *
  * @param {ol.layer.Layer} layer Layer.
  * @protected
  */
@@ -297,6 +308,8 @@ ol.control.Attribution.prototype.handleMapChanged = function() {
 
 
 /**
+ * Clears attribution and triggers refill whenever layers get added to the map
+ * or are removed from the map.
  * @protected
  */
 ol.control.Attribution.prototype.handleMapLayersChanged = function() {
@@ -304,15 +317,19 @@ ol.control.Attribution.prototype.handleMapLayersChanged = function() {
     goog.array.forEach(this.layersListenerKeys_, goog.events.unlistenByKey);
     this.layersListenerKeys_ = null;
   }
+  // Clear all attributions
   goog.object.forEach(this.attributionElements_, function(attributionElement) {
     goog.dom.removeNode(attributionElement);
   }, this);
+
   this.attributionElements_ = {};
   this.coverageAreass_ = {};
   var map = this.getMap();
   var layers = map.getLayers();
   if (goog.isDefAndNotNull(layers)) {
+    // Add attribution for layer
     layers.forEach(this.addLayer, this);
+
     this.layersListenerKeys_ = [
       goog.events.listen(layers, ol.CollectionEventType.ADD,
           this.handleLayersAdd, false, this),
@@ -378,6 +395,8 @@ ol.control.Attribution.prototype.setMap = function(map) {
 
 
 /**
+ * Shows or hides attribution for a layer. The attribution is shown whenever the
+ * layer is visible to the user.
  * @param {ol.layer.Layer} layer Layer.
  * @param {boolean} mapIsDef Map is defined.
  * @param {ol.Extent} mapExtent Map extent.

src/ol/control/control.js

@@ -14,6 +14,9 @@ ol.control.ControlOptions;
 
 
 /**
+ * A thing which is painted over the map to provide a means for interaction
+ * (buttons) of show annotations (status bars).
+ *
  * @constructor
  * @extends {goog.Disposable}
  * @param {ol.control.ControlOptions} controlOptions Control options.
@@ -67,6 +70,10 @@ ol.control.Control.prototype.getMap = function() {
 
 
 /**
+ * Removes the control from its current map and attaches it to the new map.
+ * Subtypes might also wish set up event handlers to get notified about changes
+ * to the map here.
+ *
  * @param {ol.Map} map Map.
  */
 ol.control.Control.prototype.setMap = function(map) {