Simplify the way we annotate observable properties

We no longer add observable annotations to the constructor.
Instead, we just mark getters (and for read/write properties
also setters) with an observable annotation.

apidoc/plugins/observable.js

@@ -1,29 +1,67 @@
 var util = require('util');
+
+var classes = {};
+var observables = {};
+
+exports.handlers = {
+
+  newDoclet: function(e) {
+    var doclet = e.doclet;
+    if (doclet.kind == 'class') {
+      classes[doclet.longname] = doclet;
+    }
+  },
+
+  parseComplete: function(e) {
+    var doclets = e.doclets;
+    var cls, doclet, i, ii, observable;
+    for (i = 0, ii = doclets.length - 1; i < ii; ++i) {
+      doclet = doclets[i];
+      cls = classes[doclet.longname.split('#')[0]];
+      if (typeof doclet.observable == 'string' && cls) {
+        var name = doclet.name.replace(/^[sg]et/, '');
+        name = name.substr(0, 1).toLowerCase() + name.substr(1);
+        var key = doclet.longname.split('#')[0] + '#' + name;
+        doclet.observable = key;
+        if (!observables[key]) {
+          observables[key] = {};
+        }
+        observable = observables[key];
+        observable.name = name;
+        observable.readonly = typeof observable.readonly == 'boolean' ?
+            observable.readonly : true;
+        if (doclet.name.indexOf('get') === 0) {
+          observable.type = doclet.returns[0].type;
+          observable.description = doclet.returns[0].description;
+        } else if (doclet.name.indexOf('set') === 0) {
+          observable.readonly = false;
+        }
+        if (!cls.observables) {
+          cls.observables = [];
+        }
+        observable = observables[doclet.observable];
+        if (cls.observables.indexOf(observable) == -1) {
+          cls.observables.push(observable);
+        }
+        if (!cls.fires) {
+          cls.fires = [];
+        }
+        if (cls.fires.indexOf('ol.ObjectEvent') === -1) {
+          cls.fires.push('ol.ObjectEvent');
+        }
+      }
+    }
+  }
+
+};
+
 exports.defineTags = function(dictionary) {
   dictionary.defineTag('observable', {
-    mustHaveValue: true,
+    mustNotHaveValue: true,
-    canHaveType: true,
+    canHaveType: false,
-    canHaveName: true,
+    canHaveName: false,
     onTagged: function(doclet, tag) {
-      if (!doclet.observables) {
+      doclet.observable = '';
-        doclet.observables = [];
-      }
-      var description = tag.value.description;
-      var readonly = description.split(' ').shift() === 'readonly';
-      if (readonly) {
-        description = description.split(' ').slice(1).join(' ');
-      }
-      doclet.observables.push({
-        name: tag.value.name,
-        type: {
-          names: tag.value.type.names
-        },
-        description: description,
-        readonly: readonly
-      });
-      if (!doclet.fires) {
-        doclet.fires = [];
-      }
     }
   });
 };

apidoc/plugins/todo.js

@@ -9,22 +9,7 @@ exports.defineTags = function(dictionary) {
       if (parts[0] === 'api') {
         doclet.stability = parts.slice(1).join(' ') || 'experimental';
       } else if (parts[0] === 'observable') {
-        if (!doclet.observables) {
+        doclet.observable = '';
-          doclet.observables = [];
-        }
-        var readonly = parts.length > 3 && parts[3] === 'readonly';
-        var description = (readonly ? parts.slice(4) : parts.slice(3)).join(' ');
-        doclet.observables.push({
-          name: parts[1],
-          type: {
-            names: tag.value.type.names
-          },
-          description: description,
-          readonly: readonly
-        });
-        if (!doclet.fires) {
-          doclet.fires = [];
-        }
       }
     }
   });

src/ol/collection.js

@@ -69,7 +69,6 @@ ol.CollectionProperty = {
  * @extends {ol.Object}
  * @fires ol.CollectionEvent
  * @param {Array=} opt_array Array.
- * @todo observable length {number} readonly the length of the array
  * @todo api
  */
 ol.Collection = function(opt_array) {
@@ -153,7 +152,8 @@ ol.Collection.prototype.getAt = function(index) {
 
 /**
  * Get the length of this collection.
- * @return {number} Length.
+ * @return {number} The length of the array.
+ * @todo observable
  * @todo api
  */
 ol.Collection.prototype.getLength = function() {

src/ol/control/mousepositioncontrol.js

@@ -38,10 +38,6 @@ ol.control.MousePositionProperty = {
  * @extends {ol.control.Control}
  * @param {olx.control.MousePositionOptions=} opt_options Mouse position
  *     options.
- * @todo observable projection {ol.proj.Projection} the projection to report
- *       mouse position in
- * @todo observable coordinateFormat {ol.CoordinateFormatType} the format to
- *       render the current position in
  * @todo api
  */
 ol.control.MousePosition = function(opt_options) {
@@ -132,7 +128,9 @@ ol.control.MousePosition.prototype.handleProjectionChanged_ = function() {
 
 
 /**
- * @return {ol.CoordinateFormatType|undefined} Coordinate format.
+ * @return {ol.CoordinateFormatType|undefined} The format to render the current
+ *     position in.
+ * @todo observable
  * @todo api
  */
 ol.control.MousePosition.prototype.getCoordinateFormat = function() {
@@ -146,7 +144,9 @@ goog.exportProperty(
 
 
 /**
- * @return {ol.proj.Projection|undefined} Projection.
+ * @return {ol.proj.Projection|undefined} The projection to report mouse
+ *     position in.
+ * @todo observable
  * @todo api
  */
 ol.control.MousePosition.prototype.getProjection = function() {
@@ -201,7 +201,9 @@ ol.control.MousePosition.prototype.setMap = function(map) {
 
 
 /**
- * @param {ol.CoordinateFormatType} format Coordinate format.
+ * @param {ol.CoordinateFormatType} format The format to render the current
+ *     position in.
+ * @todo observable
  * @todo api
  */
 ol.control.MousePosition.prototype.setCoordinateFormat = function(format) {
@@ -214,7 +216,9 @@ goog.exportProperty(
 
 
 /**
- * @param {ol.proj.Projection} projection Projection.
+ * @param {ol.proj.Projection} projection The projection to report mouse
+ *     position in.
+ * @todo observable
  * @todo api
  */
 ol.control.MousePosition.prototype.setProjection = function(projection) {

src/ol/control/scalelinecontrol.js

@@ -50,8 +50,6 @@ ol.control.ScaleLineUnits = {
  * @constructor
  * @extends {ol.control.Control}
  * @param {olx.control.ScaleLineOptions=} opt_options Scale line options.
- * @todo observable units {ol.control.ScaleLineUnits} the units to use in the
- *       scale line
  * @todo api
  */
 ol.control.ScaleLine = function(opt_options) {
@@ -137,7 +135,9 @@ ol.control.ScaleLine.LEADING_DIGITS = [1, 2, 5];
 
 
 /**
- * @return {ol.control.ScaleLineUnits|undefined} units.
+ * @return {ol.control.ScaleLineUnits|undefined} The units to use in the scale
+ *     line.
+ * @todo observable
  * @todo api
  */
 ol.control.ScaleLine.prototype.getUnits = function() {
@@ -173,7 +173,8 @@ ol.control.ScaleLine.prototype.handleUnitsChanged_ = function() {
 
 
 /**
- * @param {ol.control.ScaleLineUnits} units Units.
+ * @param {ol.control.ScaleLineUnits} units The units to use in the scale line.
+ * @todo observable
  * @todo api
  */
 ol.control.ScaleLine.prototype.setUnits = function(units) {

src/ol/deviceorientation.js

@@ -69,16 +69,6 @@ ol.DeviceOrientationProperty = {
  * @constructor
  * @extends {ol.Object}
  * @param {olx.DeviceOrientationOptions=} opt_options Options.
- * @todo observable alpha {number} readonly the euler angle in radians of the
- *       device from the standard X axis
- * @todo observable beta {number} readonly the euler angle in radians of the
- *       device from the planar Z axis
- * @todo observable gamma {number} readonly the euler angle in radians of the
- *       device from the planar X axis
- * @todo observable heading {number} readonly the euler angle in radians of the
- *       device from the planar Y axis
- * @todo observable tracking {boolean} the status of tracking changes to alpha,
- *       beta and gamma.  If true, changes are tracked and reported immediately.
  * @todo api
  */
 ol.DeviceOrientation = function(opt_options) {
@@ -145,8 +135,9 @@ ol.DeviceOrientation.prototype.orientationChange_ = function(browserEvent) {
 
 
 /**
- * @return {number|undefined} The alpha value of the DeviceOrientation,
+ * @return {number|undefined} The euler angle in radians of the device from the
- * in radians.
+ *     standard Z axis.
+ * @todo observable
  * @todo api
  */
 ol.DeviceOrientation.prototype.getAlpha = function() {
@@ -160,8 +151,9 @@ goog.exportProperty(
 
 
 /**
- * @return {number|undefined} The beta value of the DeviceOrientation,
+ * @return {number|undefined} The euler angle in radians of the device from the
- * in radians.
+ *     planar X axis.
+ * @todo observable
  * @todo api
  */
 ol.DeviceOrientation.prototype.getBeta = function() {
@@ -175,8 +167,9 @@ goog.exportProperty(
 
 
 /**
- * @return {number|undefined} The gamma value of the DeviceOrientation,
+ * @return {number|undefined} The euler angle in radians of the device from the
- * in radians.
+ *     planar Y axis.
+ * @todo observable
  * @todo api
  */
 ol.DeviceOrientation.prototype.getGamma = function() {
@@ -190,8 +183,9 @@ goog.exportProperty(
 
 
 /**
- * @return {number|undefined} The heading of the device relative to
+ * @return {number|undefined} The heading of the device relative to north, in
- * north, in radians, normalizing for different browser behavior.
+ *     radians, normalizing for different browser behavior.
+ * @todo observable
  * @todo api
  */
 ol.DeviceOrientation.prototype.getHeading = function() {
@@ -206,7 +200,9 @@ goog.exportProperty(
 
 /**
  * Are we tracking the device's orientation?
- * @return {boolean} The current tracking state, true if tracking is on.
+ * @return {boolean} The status of tracking changes to alpha, beta and gamma.
+ *     If true, changes are tracked and reported immediately.
+ * @todo observable
  * @todo api
  */
 ol.DeviceOrientation.prototype.getTracking = function() {
@@ -238,7 +234,9 @@ ol.DeviceOrientation.prototype.handleTrackingChanged_ = function() {
 
 /**
  * Enable or disable tracking of DeviceOrientation events.
- * @param {boolean} tracking True to enable and false to disable tracking.
+ * @param {boolean} tracking The status of tracking changes to alpha, beta and
+ *     gamma. If true, changes are tracked and reported immediately.
+ * @todo observable
  * @todo api
  */
 ol.DeviceOrientation.prototype.setTracking = function(tracking) {

src/ol/dom/input.js

@@ -29,8 +29,6 @@ ol.dom.InputProperty = {
  * @constructor
  * @extends {ol.Object}
  * @param {Element} target Target element.
- * @todo observable value {string} the value of the Input
- * @todo observable checked {boolean} the checked state of the Input
  * @todo api
  */
 ol.dom.Input = function(target) {
@@ -58,7 +56,8 @@ goog.inherits(ol.dom.Input, ol.Object);
 
 /**
  * If the input is a checkbox, return whether or not the checbox is checked.
- * @return {boolean|undefined} checked.
+ * @return {boolean|undefined} The checked state of the Input.
+ * @todo observable
  * @todo api
  */
 ol.dom.Input.prototype.getChecked = function() {
@@ -72,7 +71,8 @@ goog.exportProperty(
 
 /**
  * Get the value of the input.
- * @return {string|undefined} input value.
+ * @return {string|undefined} The value of the Input.
+ * @todo observable
  * @todo api
  */
 ol.dom.Input.prototype.getValue = function() {
@@ -86,7 +86,8 @@ goog.exportProperty(
 
 /**
  * Sets the value of the input.
- * @param {string} value Value.
+ * @param {string} value The value of the Input.
+ * @todo observable
  * @todo api
  */
 ol.dom.Input.prototype.setValue = function(value) {
@@ -100,7 +101,8 @@ goog.exportProperty(
 
 /**
  * Set whether or not a checkbox is checked.
- * @param {boolean} checked Checked.
+ * @param {boolean} checked The checked state of the Input.
+ * @todo observable
  * @todo api
  */
 ol.dom.Input.prototype.setChecked = function(checked) {

src/ol/geolocation.js

@@ -51,26 +51,6 @@ ol.GeolocationProperty = {
  * @constructor
  * @extends {ol.Object}
  * @param {olx.GeolocationOptions=} opt_options Options.
- * @todo observable accuracy {number} readonly the accuracy of the position
- *       measurement in meters
- * @todo observable accuracyGeometry {ol.geom.Geometry} readonly a
- *       geometry of the position accuracy.
- * @todo observable altitude {number} readonly the altitude of the position in
- *       meters above mean sea level
- * @todo observable altitudeAccuracy {number} readonly the accuracy of the
- *       altitude measurement in meters
- * @todo observable heading {number} readonly the heading of the device in
- *       radians from north
- * @todo observable position {ol.Coordinate} readonly the current position of
- *       the device reported in the current projection
- * @todo observable projection {ol.proj.Projection} readonly the projection to
- *       report the position in
- * @todo observable speed {number} readonly the instantaneous speed of the
- *       device in meters per second
- * @todo observable tracking {number} track the device's position.
- * @todo observable trackingOptions {GeolocationPositionOptions} PositionOptions
- *       as defined by the HTML5 Geolocation spec at
- *       http://www.w3.org/TR/geolocation-API/#position_options_interface
  * @todo api
  */
 ol.Geolocation = function(opt_options) {
@@ -205,7 +185,9 @@ ol.Geolocation.prototype.positionError_ = function(error) {
 
 /**
  * Get the accuracy of the position in meters.
- * @return {number|undefined} Position accuracy in meters.
+ * @return {number|undefined} The accuracy of the position measurement in
+ *     meters.
+ * @todo observable
  * @todo api
  */
 ol.Geolocation.prototype.getAccuracy = function() {
@@ -220,7 +202,8 @@ goog.exportProperty(
 
 /**
  * Get a geometry of the position accuracy.
- * @return {?ol.geom.Geometry} Accuracy geometry.
+ * @return {?ol.geom.Geometry} A geometry of the position accuracy.
+ * @todo observable
  * @todo api
  */
 ol.Geolocation.prototype.getAccuracyGeometry = function() {
@@ -235,7 +218,9 @@ goog.exportProperty(
 
 /**
  * Get the altitude associated with the position.
- * @return {number|undefined} The altitude in meters above the mean sea level.
+ * @return {number|undefined} The altitude of the position in meters above mean
+ *     sea level.
+ * @todo observable
  * @todo api
  */
 ol.Geolocation.prototype.getAltitude = function() {
@@ -250,7 +235,9 @@ goog.exportProperty(
 
 /**
  * Get the altitude accuracy of the position.
- * @return {number|undefined} Altitude accuracy in meters.
+ * @return {number|undefined} The accuracy of the altitude measurement in
+ *     meters.
+ * @todo observable
  * @todo api
  */
 ol.Geolocation.prototype.getAltitudeAccuracy = function() {
@@ -265,7 +252,8 @@ goog.exportProperty(
 
 /**
  * Get the heading as radians clockwise from North.
- * @return {number|undefined} Heading.
+ * @return {number|undefined} The heading of the device in radians from north.
+ * @todo observable
  * @todo api
  */
 ol.Geolocation.prototype.getHeading = function() {
@@ -280,7 +268,9 @@ goog.exportProperty(
 
 /**
  * Get the position of the device.
- * @return {ol.Coordinate|undefined} position.
+ * @return {ol.Coordinate|undefined} The current position of the device reported
+ *     in the current projection.
+ * @todo observable
  * @todo api
  */
 ol.Geolocation.prototype.getPosition = function() {
@@ -295,7 +285,9 @@ goog.exportProperty(
 
 /**
  * Get the projection associated with the position.
- * @return {ol.proj.Projection|undefined} projection.
+ * @return {ol.proj.Projection|undefined} The projection the position is
+ *     reported in.
+ * @todo observable
  * @todo api
  */
 ol.Geolocation.prototype.getProjection = function() {
@@ -310,7 +302,9 @@ goog.exportProperty(
 
 /**
  * Get the speed in meters per second.
- * @return {number|undefined} Speed.
+ * @return {number|undefined} The instantaneous speed of the device in meters
+ *     per second.
+ * @todo observable
  * @todo api
  */
 ol.Geolocation.prototype.getSpeed = function() {
@@ -325,7 +319,8 @@ goog.exportProperty(
 
 /**
  * Are we tracking the user's position?
- * @return {boolean} tracking.
+ * @return {boolean} Whether to track the device's position.
+ * @todo observable
  * @todo api
  */
 ol.Geolocation.prototype.getTracking = function() {
@@ -341,8 +336,10 @@ goog.exportProperty(
 /**
  * Get the tracking options.
  * @see http://www.w3.org/TR/geolocation-API/#position-options
- * @return {GeolocationPositionOptions|undefined} HTML 5 Gelocation
+ * @return {GeolocationPositionOptions|undefined} PositionOptions as defined by
- * tracking options.
+ *     the HTML5 Geolocation spec at
+ *     {@link http://www.w3.org/TR/geolocation-API/#position_options_interface}
+ * @todo observable
  * @todo api
  */
 ol.Geolocation.prototype.getTrackingOptions = function() {
@@ -357,7 +354,9 @@ goog.exportProperty(
 
 /**
  * Set the projection to use for transforming the coordinates.
- * @param {ol.proj.Projection} projection Projection.
+ * @param {ol.proj.Projection} projection The projection the position is
+ *     reported in.
+ * @todo observable
  * @todo api
  */
 ol.Geolocation.prototype.setProjection = function(projection) {
@@ -371,7 +370,8 @@ goog.exportProperty(
 
 /**
  * Enable/disable tracking.
- * @param {boolean} tracking Enable or disable tracking.
+ * @param {boolean} tracking Whether to track the device's position.
+ * @todo observable
  * @todo api
  */
 ol.Geolocation.prototype.setTracking = function(tracking) {
@@ -386,8 +386,10 @@ goog.exportProperty(
 /**
  * Set the tracking options.
  * @see http://www.w3.org/TR/geolocation-API/#position-options
- * @param {GeolocationPositionOptions} options HTML 5 Geolocation
+ * @param {GeolocationPositionOptions} options PositionOptions as defined by the
- * tracking options.
+ *     HTML5 Geolocation spec at
+ *     {@link http://www.w3.org/TR/geolocation-API/#position_options_interface}
+ * @todo observable
  * @todo api
  */
 ol.Geolocation.prototype.setTrackingOptions = function(options) {

src/ol/iview.js

@@ -8,6 +8,7 @@ goog.require('ol.IView3D');
 /**
  * Interface for views.
  * @interface
+ * @extends {goog.events.Listenable}
  */
 ol.IView = function() {
 };

src/ol/iview2d.js

@@ -13,28 +13,28 @@ ol.IView2D = function() {
 
 
 /**
- * @return {ol.Coordinate|undefined} Map center.
+ * @return {ol.Coordinate|undefined} The center of the view.
  */
 ol.IView2D.prototype.getCenter = function() {
 };
 
 
 /**
- * @return {ol.proj.Projection|undefined} Map projection.
+ * @return {ol.proj.Projection|undefined} The projection of the view.
  */
 ol.IView2D.prototype.getProjection = function() {
 };
 
 
 /**
- * @return {number|undefined} Map resolution.
+ * @return {number|undefined} The resolution of the view.
  */
 ol.IView2D.prototype.getResolution = function() {
 };
 
 
 /**
- * @return {number|undefined} Map rotation.
+ * @return {number|undefined} The rotation of the view.
  */
 ol.IView2D.prototype.getRotation = function() {
 };

src/ol/layer/layer.js

@@ -14,14 +14,6 @@ goog.require('ol.source.Source');
  * @extends {ol.layer.Base}
  * @fires ol.render.Event
  * @param {olx.layer.LayerOptions} options Layer options.
- * @todo observable brightness {number} the brightness of the layer
- * @todo observable contrast {number} the contrast of the layer
- * @todo observable hue {number} the hue of the layer
- * @todo observable opacity {number} the opacity of the layer
- * @todo observable saturation {number} the saturation of the layer
- * @todo observable visible {boolean} the visiblity of the layer
- * @todo observable maxResolution {number} the maximum resolution of the layer
- * @todo observable minResolution {number} the minimum resolution of the layer
  * @todo api
  */
 ol.layer.Layer = function(options) {

src/ol/layer/layerbase.js

@@ -77,7 +77,8 @@ goog.inherits(ol.layer.Base, ol.Object);
 
 
 /**
- * @return {number|undefined} Brightness.
+ * @return {number|undefined} The brightness of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.getBrightness = function() {
@@ -91,7 +92,8 @@ goog.exportProperty(
 
 
 /**
- * @return {number|undefined} Contrast.
+ * @return {number|undefined} The contrast of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.getContrast = function() {
@@ -105,7 +107,8 @@ goog.exportProperty(
 
 
 /**
- * @return {number|undefined} Hue.
+ * @return {number|undefined} The hue of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.getHue = function() {
@@ -162,7 +165,8 @@ ol.layer.Base.prototype.getLayerStatesArray = goog.abstractMethod;
 
 
 /**
- * @return {number|undefined} MaxResolution.
+ * @return {number|undefined} The maximum resolution of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.getMaxResolution = function() {
@@ -176,7 +180,8 @@ goog.exportProperty(
 
 
 /**
- * @return {number|undefined} MinResolution.
+ * @return {number|undefined} The minimum resolution of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.getMinResolution = function() {
@@ -190,7 +195,8 @@ goog.exportProperty(
 
 
 /**
- * @return {number|undefined} Opacity.
+ * @return {number|undefined} The opacity of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.getOpacity = function() {
@@ -204,7 +210,8 @@ goog.exportProperty(
 
 
 /**
- * @return {number|undefined} Saturation.
+ * @return {number|undefined} The saturation of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.getSaturation = function() {
@@ -224,7 +231,8 @@ ol.layer.Base.prototype.getSourceState = goog.abstractMethod;
 
 
 /**
- * @return {boolean|undefined} Visible.
+ * @return {boolean|undefined} The visiblity of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.getVisible = function() {
@@ -255,7 +263,8 @@ goog.exportProperty(
  * [2] https://github.com/WebKit/webkit/commit/8f4765e569
  * [3] https://www.w3.org/Bugs/Public/show_bug.cgi?id=15647
  *
- * @param {number|undefined} brightness Brightness.
+ * @param {number|undefined} brightness The brightness of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.setBrightness = function(brightness) {
@@ -272,7 +281,8 @@ goog.exportProperty(
  * grey.  A value of 1 will leave the contrast unchanged.  Other values are
  * linear multipliers on the effect (and values over 1 are permitted).
  *
- * @param {number|undefined} contrast Contrast.
+ * @param {number|undefined} contrast The contrast of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.setContrast = function(contrast) {
@@ -287,7 +297,8 @@ goog.exportProperty(
 /**
  * Apply a hue-rotation to the layer.  A value of 0 will leave the hue
  * unchanged.  Other values are radians around the color circle.
- * @param {number|undefined} hue Hue.
+ * @param {number|undefined} hue The hue of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.setHue = function(hue) {
@@ -300,7 +311,8 @@ goog.exportProperty(
 
 
 /**
- * @param {number|undefined} maxResolution MaxResolution.
+ * @param {number|undefined} maxResolution The maximum resolution of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.setMaxResolution = function(maxResolution) {
@@ -313,7 +325,8 @@ goog.exportProperty(
 
 
 /**
- * @param {number|undefined} minResolution MinResolution.
+ * @param {number|undefined} minResolution The minimum resolution of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.setMinResolution = function(minResolution) {
@@ -326,7 +339,8 @@ goog.exportProperty(
 
 
 /**
- * @param {number|undefined} opacity Opacity.
+ * @param {number|undefined} opacity The opacity of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.setOpacity = function(opacity) {
@@ -344,7 +358,8 @@ goog.exportProperty(
  * values are linear multipliers of the effect (and values over 1 are
  * permitted).
  *
- * @param {number|undefined} saturation Saturation.
+ * @param {number|undefined} saturation The saturation of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.setSaturation = function(saturation) {
@@ -357,7 +372,8 @@ goog.exportProperty(
 
 
 /**
- * @param {boolean|undefined} visible Visible.
+ * @param {boolean|undefined} visible The visiblity of the layer.
+ * @todo observable
  * @todo api
  */
 ol.layer.Base.prototype.setVisible = function(visible) {

src/ol/layer/layergroup.js

@@ -28,8 +28,6 @@ ol.layer.GroupProperty = {
  * @constructor
  * @extends {ol.layer.Base}
  * @param {olx.layer.GroupOptions=} opt_options Layer options.
- * @todo observable layers {ol.Collection} collection of {@link ol.layer} layers
- *       that are part of this group
  * @todo api
  */
 ol.layer.Group = function(opt_options) {
@@ -142,7 +140,9 @@ ol.layer.Group.prototype.handleLayersRemove_ = function(collectionEvent) {
 
 
 /**
- * @return {ol.Collection|undefined} Collection of layers.
+ * @return {ol.Collection|undefined} Collection of {@link ol.layer.Layer layers}
+ *     that are part of this group.
+ * @todo observable
  */
 ol.layer.Group.prototype.getLayers = function() {
   return /** @type {ol.Collection|undefined} */ (this.get(
@@ -155,7 +155,9 @@ goog.exportProperty(
 
 
 /**
- * @param {ol.Collection|undefined} layers Collection of layers.
+ * @param {ol.Collection|undefined} layers Collection of
+ * {@link ol.layer.Layer layers} that are part of this group.
+ * @todo observable
  */
 ol.layer.Group.prototype.setLayers = function(layers) {
   this.set(ol.layer.GroupProperty.LAYERS, layers);

src/ol/layer/tilelayer.js

@@ -18,7 +18,6 @@ ol.layer.TileProperty = {
  * @extends {ol.layer.Layer}
  * @fires ol.render.Event
  * @param {olx.layer.TileOptions} options Tile layer options.
- * @todo observable preload {number} the level to preload tiles up to
  * @todo api
  */
 ol.layer.Tile = function(options) {
@@ -29,7 +28,8 @@ goog.inherits(ol.layer.Tile, ol.layer.Layer);
 
 
 /**
- * @return {number|undefined} Preload.
+ * @return {number|undefined} The level to preload tiles up to.
+ * @todo observable
  */
 ol.layer.Tile.prototype.getPreload = function() {
   return /** @type {number|undefined} */ (
@@ -42,7 +42,8 @@ goog.exportProperty(
 
 
 /**
- * @param {number} preload Preload.
+ * @param {number} preload The level to preload tiles up to.
+ * @todo observable
  */
 ol.layer.Tile.prototype.setPreload = function(preload) {
   this.set(ol.layer.TileProperty.PRELOAD, preload);

src/ol/map.js

@@ -156,15 +156,9 @@ ol.MapProperty = {
  * @constructor
  * @extends {ol.Object}
  * @param {olx.MapOptions} options Map options.
- * @todo observable layergroup {ol.layer.Group} a layer group containing the
  * @fires ol.MapBrowserEvent
  * @fires ol.MapEvent
  * @fires ol.render.Event
- *       layers in this map.
- * @todo observable size {ol.Size} the size in pixels of the map in the DOM
- * @todo observable target {string|Element} the Element or id of the Element
- *       that the map is rendered in.
- * @todo observable view {ol.IView} the view that controls this map
  * @todo api
  */
 ol.Map = function(options) {
@@ -614,7 +608,9 @@ ol.Map.prototype.getEventPixel = function(event) {
  * Get the target in which this map is rendered.
  * Note that this returns what is entered as an option or in setTarget:
  * if that was an element, it returns an element; if a string, it returns that.
- * @return {Element|string|undefined} Target.
+ * @return {Element|string|undefined} The Element or id of the Element that the
+ *     map is rendered in.
+ * @todo observable
  * @todo api
  */
 ol.Map.prototype.getTarget = function() {
@@ -677,7 +673,8 @@ ol.Map.prototype.getInteractions = function() {
 
 /**
  * Get the layergroup associated with this map.
- * @return {ol.layer.Group} LayerGroup.
+ * @return {ol.layer.Group} A layer group containing the layers in this map.
+ * @todo observable
  * @todo api
  */
 ol.Map.prototype.getLayerGroup = function() {
@@ -723,7 +720,8 @@ ol.Map.prototype.getPixelFromCoordinate = function(coordinate) {
 
 /**
  * Get the size of this map.
- * @return {ol.Size|undefined} Size.
+ * @return {ol.Size|undefined} The size in pixels of the map in the DOM.
+ * @todo observable
  * @todo api
  */
 ol.Map.prototype.getSize = function() {
@@ -738,11 +736,12 @@ goog.exportProperty(
 /**
  * Get the view associated with this map. This can be a 2D or 3D view. A 2D
  * view manages properties such as center and resolution.
- * @return {ol.View|undefined} View.
+ * @return {ol.IView|undefined} The view that controls this map.
+ * @todo observable
  * @todo api
  */
 ol.Map.prototype.getView = function() {
-  return /** @type {ol.View} */ (this.get(ol.MapProperty.VIEW));
+  return /** @type {ol.IView} */ (this.get(ol.MapProperty.VIEW));
 };
 goog.exportProperty(
     ol.Map.prototype,
@@ -1255,7 +1254,9 @@ ol.Map.prototype.renderFrame_ = function(time) {
 
 /**
  * Sets the layergroup of this map.
- * @param {ol.layer.Group} layerGroup Layergroup.
+ * @param {ol.layer.Group} layerGroup A layer group containing the layers in
+ *     this map.
+ * @todo observable
  * @todo api
  */
 ol.Map.prototype.setLayerGroup = function(layerGroup) {
@@ -1269,7 +1270,8 @@ goog.exportProperty(
 
 /**
  * Set the size of this map.
- * @param {ol.Size|undefined} size Size.
+ * @param {ol.Size|undefined} size The size in pixels of the map in the DOM.
+ * @todo observable
  * @todo api
  */
 ol.Map.prototype.setSize = function(size) {
@@ -1283,7 +1285,9 @@ goog.exportProperty(
 
 /**
  * Set the target element to render this map into.
- * @param {Element|string|undefined} target Target.
+ * @param {Element|string|undefined} target The Element or id of the Element
+ *     that the map is rendered in.
+ * @todo observable
  * @todo api
  */
 ol.Map.prototype.setTarget = function(target) {
@@ -1296,8 +1300,9 @@ goog.exportProperty(
 
 
 /**
- * Set the view for this map. Currently {@link ol.View2D} is implememnted.
+ * Set the view for this map.
- * @param {ol.IView} view View.
+ * @param {ol.IView} view The view that controls this map.
+ * @todo observable
  * @todo api
  */
 ol.Map.prototype.setView = function(view) {

src/ol/overlay.js

@@ -59,12 +59,6 @@ ol.OverlayPositioning = {
  * @constructor
  * @extends {ol.Object}
  * @param {olx.OverlayOptions} options Overlay options.
- * @todo observable element {Element} the Element containing the overlay
- * @todo observable map {ol.Map} the map that the overlay is part of
- * @todo observable position {ol.Coordinate} the spatial point that the overlay
- *       is anchored at
- * @todo observable positioning {ol.OverlayPositioning} how the overlay is
- *       positioned relative to its point on the map
  * @todo api stable
  */
 ol.Overlay = function(options) {
@@ -159,7 +153,8 @@ goog.inherits(ol.Overlay, ol.Object);
 
 /**
  * Get the DOM element of this overlay.
- * @return {Element|undefined} Element.
+ * @return {Element|undefined} The Element containing the overlay.
+ * @todo observable
  * @todo api
  */
 ol.Overlay.prototype.getElement = function() {
@@ -174,7 +169,8 @@ goog.exportProperty(
 
 /**
  * Get the map associated with this overlay.
- * @return {ol.Map|undefined} Map.
+ * @return {ol.Map|undefined} The map that the overlay is part of.
+ * @todo observable
  * @todo api
  */
 ol.Overlay.prototype.getMap = function() {
@@ -189,7 +185,9 @@ goog.exportProperty(
 
 /**
  * Get the current position of this overlay.
- * @return {ol.Coordinate|undefined} Position.
+ * @return {ol.Coordinate|undefined} The spatial point that the overlay is
+ *     anchored at.
+ * @todo observable
  * @todo api
  */
 ol.Overlay.prototype.getPosition = function() {
@@ -204,7 +202,9 @@ goog.exportProperty(
 
 /**
  * Get the current positioning of this overlay.
- * @return {ol.OverlayPositioning|undefined} Positioning.
+ * @return {ol.OverlayPositioning|undefined} How the overlay is positioned
+ *     relative to its point on the map.
+ * @todo observable
  * @todo api
  */
 ol.Overlay.prototype.getPositioning = function() {
@@ -281,7 +281,8 @@ ol.Overlay.prototype.handlePositioningChanged = function() {
 
 /**
  * Set the DOM element to be associated with this overlay.
- * @param {Element|undefined} element Element.
+ * @param {Element|undefined} element The Element containing the overlay.
+ * @todo observable
  * @todo api
  */
 ol.Overlay.prototype.setElement = function(element) {
@@ -295,7 +296,8 @@ goog.exportProperty(
 
 /**
  * Set the map to be associated with this overlay.
- * @param {ol.Map|undefined} map Map.
+ * @param {ol.Map|undefined} map The map that the overlay is part of.
+ * @todo observable
  * @todo api
  */
 ol.Overlay.prototype.setMap = function(map) {
@@ -309,7 +311,9 @@ goog.exportProperty(
 
 /**
  * Set the position for this overlay.
- * @param {ol.Coordinate|undefined} position Position.
+ * @param {ol.Coordinate|undefined} position The spatial point that the overlay
+ *     is anchored at.
+ * @todo observable
  * @todo api stable
  */
 ol.Overlay.prototype.setPosition = function(position) {
@@ -323,7 +327,9 @@ goog.exportProperty(
 
 /**
  * Set the positioning for this overlay.
- * @param {ol.OverlayPositioning|undefined} positioning Positioning.
+ * @param {ol.OverlayPositioning|undefined} positioning how the overlay is
+ *     positioned relative to its point on the map.
+ * @todo observable
  * @todo api
  */
 ol.Overlay.prototype.setPositioning = function(positioning) {

src/ol/source/source.js

@@ -9,7 +9,10 @@ goog.require('ol.proj');
 
 
 /**
+ * State of the source. `0` means 'loading', `1` means 'ready', and `2` means
+ * 'error'.
  * @enum {number}
+ * @todo api
  */
 ol.source.State = {
   LOADING: 0,

src/ol/view2d.js

@@ -86,10 +86,6 @@ ol.View2DProperty = {
  * @implements {ol.IView3D}
  * @extends {ol.View}
  * @param {olx.View2DOptions=} opt_options View2D options.
- * @todo observable center {ol.Coordinate} the center of the view
- * @todo observable projection {ol.proj.Projection} the projection of the view
- * @todo observable resolution {number} the resolution of the view
- * @todo observable rotation {number} the rotation of the view
  * @todo api
  */
 ol.View2D = function(opt_options) {
@@ -221,6 +217,7 @@ ol.View2D.prototype.constrainRotation = function(rotation, opt_delta) {
 
 /**
  * @inheritDoc
+ * @todo observable
  * @todo api
  */
 ol.View2D.prototype.getCenter = function() {
@@ -254,6 +251,7 @@ ol.View2D.prototype.calculateExtent = function(size) {
 
 /**
  * @inheritDoc
+ * @todo observable
  * @todo api
  */
 ol.View2D.prototype.getProjection = function() {
@@ -268,6 +266,7 @@ goog.exportProperty(
 
 /**
  * @inheritDoc
+ * @todo observable
  * @todo api
  */
 ol.View2D.prototype.getResolution = function() {
@@ -319,6 +318,7 @@ ol.View2D.prototype.getResolutionForValueFunction = function(opt_power) {
 
 /**
  * @inheritDoc
+ * @todo observable
  * @todo api
  */
 ol.View2D.prototype.getRotation = function() {
@@ -556,7 +556,8 @@ ol.View2D.prototype.rotate = function(rotation, opt_anchor) {
 
 /**
  * Set the center of the current view.
- * @param {ol.Coordinate|undefined} center Center.
+ * @param {ol.Coordinate|undefined} center The center of the view.
+ * @todo observable
  * @todo api
  */
 ol.View2D.prototype.setCenter = function(center) {
@@ -571,7 +572,8 @@ goog.exportProperty(
 /**
  * Set the projection of this view.
  * Warning! This code is not yet implemented. Function should not be used.
- * @param {ol.proj.Projection|undefined} projection Projection.
+ * @param {ol.proj.Projection|undefined} projection The projection of the view.
+ * @todo observable
  * @todo api
  */
 ol.View2D.prototype.setProjection = function(projection) {
@@ -585,7 +587,8 @@ goog.exportProperty(
 
 /**
  * Set the resolution for this view.
- * @param {number|undefined} resolution Resolution.
+ * @param {number|undefined} resolution The resolution of the view.
+ * @todo observable
  * @todo api
  */
 ol.View2D.prototype.setResolution = function(resolution) {
@@ -599,7 +602,8 @@ goog.exportProperty(
 
 /**
  * Set the rotation for this view.
- * @param {number|undefined} rotation Rotation.
+ * @param {number|undefined} rotation The rotation of the view.
+ * @todo observable
  * @todo api
  */
 ol.View2D.prototype.setRotation = function(rotation) {