Merge pull request #2043 from ahocevar/nicer-api-docs

Nicer API docs
2014-05-07 09:20:22 -05:00
parent 596e06ed4e 0d4c7dc1fc
commit be73885e37
81 changed files with 2267 additions and 934 deletions
--- a/src/ol/collection.js
+++ b/src/ol/collection.js
@@ -67,9 +67,8 @@ ol.CollectionProperty = {
 * A mutable MVC Array.
 * @constructor
 * @extends {ol.Object}
- * @fires {@link ol.CollectionEvent} ol.CollectionEvent
+ * @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() {
--- a/src/ol/control/mousepositioncontrol.js
+++ b/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) {
--- a/src/ol/control/scalelinecontrol.js
+++ b/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) {
--- a/src/ol/coordinate.js
+++ b/src/ol/coordinate.js
@@ -17,7 +17,7 @@ ol.CoordinateFormatType;


 /**
- * An array of numbers representing a coordinate.
+ * An array of numbers representing a coordinate. Example: `[16, 48]`.
 * @typedef {Array.<number>} ol.Coordinate
 * @todo api
 */
--- a/src/ol/deviceorientation.js
+++ b/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,
- * in radians.
+ * @return {number|undefined} The euler angle in radians of the device from the
+ *     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,
- * in radians.
+ * @return {number|undefined} The euler angle in radians of the device from the
+ *     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,
- * in radians.
+ * @return {number|undefined} The euler angle in radians of the device from the
+ *     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
- * north, in radians, normalizing for different browser behavior.
+ * @return {number|undefined} The heading of the device relative to north, in
+ *     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) {
--- a/src/ol/dom/input.js
+++ b/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) {
--- a/src/ol/events/condition.jsdoc
+++ b/src/ol/events/condition.jsdoc
@@ -1,3 +1,7 @@
+/**
+ * @namespace ol.events
+ */
+
 /**
 * @namespace ol.events.condition
 */
--- a/src/ol/geolocation.js
+++ b/src/ol/geolocation.js
@@ -52,26 +52,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) {
@@ -207,7 +187,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() {
@@ -222,7 +204,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() {
@@ -237,7 +220,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() {
@@ -252,7 +237,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() {
@@ -267,7 +254,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() {
@@ -282,7 +270,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() {
@@ -297,7 +287,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() {
@@ -312,7 +304,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() {
@@ -327,7 +321,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() {
@@ -343,8 +338,10 @@ goog.exportProperty(
 /**
 * Get the tracking options.
 * @see http://www.w3.org/TR/geolocation-API/#position-options
- * @return {GeolocationPositionOptions|undefined} HTML 5 Gelocation
- * tracking options.
+ * @return {GeolocationPositionOptions|undefined} PositionOptions as defined by
+ *     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() {
@@ -359,7 +356,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) {
@@ -373,7 +372,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) {
@@ -388,8 +388,10 @@ goog.exportProperty(
 /**
 * Set the tracking options.
 * @see http://www.w3.org/TR/geolocation-API/#position-options
- * @param {GeolocationPositionOptions} options HTML 5 Geolocation
- * tracking options.
+ * @param {GeolocationPositionOptions} options PositionOptions as defined by the
+ *     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) {
--- a/src/ol/geom/geometry.js
+++ b/src/ol/geom/geometry.js
@@ -187,43 +187,56 @@ ol.geom.Geometry.prototype.transform = function(source, destination) {


 /**
+ * Array representation of a point. Example: `[16, 48]`.
 * @typedef {ol.Coordinate}
+ * @todo api
 */
 ol.geom.RawPoint;


 /**
+ * Array representation of a linsetring.
 * @typedef {Array.<ol.Coordinate>}
+ * @todo api
 */
 ol.geom.RawLineString;


 /**
+ * Array representation of a linear ring.
 * @typedef {Array.<ol.Coordinate>}
- *
+ * @todo api
 */
 ol.geom.RawLinearRing;


 /**
+ * Array representation of a polygon.
 * @typedef {Array.<ol.geom.RawLinearRing>}
+ * @todo api
 */
 ol.geom.RawPolygon;


 /**
+ * Array representation of a multipoint.
 * @typedef {Array.<ol.geom.RawPoint>}
+ * @todo api
 */
 ol.geom.RawMultiPoint;


 /**
+ * Array representation of a multilinestring.
 * @typedef {Array.<ol.geom.RawLineString>}
+ * @todo api
 */
 ol.geom.RawMultiLineString;


 /**
+ * Array representation of a multipolygon.
 * @typedef {Array.<ol.geom.RawPolygon>}
+ * @todo api
 */
 ol.geom.RawMultiPolygon;
--- a/src/ol/interaction/draganddropinteraction.js
+++ b/src/ol/interaction/draganddropinteraction.js
@@ -19,8 +19,7 @@ goog.require('ol.proj');
 /**
 * @constructor
 * @extends {ol.interaction.Interaction}
- * @fires {@link ol.interaction.DragAndDropEvent}
- *     ol.interaction.DragAndDropEvent
+ * @fires ol.interaction.DragAndDropEvent
 * @param {olx.interaction.DragAndDropOptions=} opt_options Options.
 * @todo api
 */
--- a/src/ol/interaction/dragboxinteraction.js
+++ b/src/ol/interaction/dragboxinteraction.js
@@ -76,7 +76,7 @@ goog.inherits(ol.DragBoxEvent, goog.events.Event);
 *
 * @constructor
 * @extends {ol.interaction.Pointer}
- * @fires {@link ol.DragBoxEvent} ol.DragBoxEvent
+ * @fires ol.DragBoxEvent
 * @param {olx.interaction.DragBoxOptions=} opt_options Options.
 * @todo api
 */
--- a/src/ol/interaction/drawinteraction.js
+++ b/src/ol/interaction/drawinteraction.js
@@ -68,7 +68,7 @@ goog.inherits(ol.DrawEvent, goog.events.Event);
 * Interaction that allows drawing geometries
 * @constructor
 * @extends {ol.interaction.Pointer}
- * @fires {@link ol.DrawEvent} ol.DrawEvent
+ * @fires ol.DrawEvent
 * @param {olx.interaction.DrawOptions} options Options.
 * @todo api
 */
--- a/src/ol/interaction/interactiondefaults.js
+++ b/src/ol/interaction/interactiondefaults.js
@@ -19,9 +19,9 @@ goog.require('ol.interaction.PinchZoom');
 * setting the appropriate option to false in the constructor options,
 * but the order of the interactions is fixed.  If you want to specify a
 * different order for interactions, you will need to create your own
- * {@link ol.interaction} instances and insert them into an
- * {@link ol.Collection} in the order you want before creating your ol.Map
- * instance.
+ * {@link ol.interaction.Interaction} instances and insert them into a
+ * {@link ol.Collection} in the order you want before creating your
+ * {@link ol.Map} instance.
 * @param {olx.interaction.DefaultsOptions=} opt_options Defaults options.
 * @return {ol.Collection} A collection of interactions to be used with
 * the ol.Map constructor's interactions option.
--- a/src/ol/iview.js
+++ b/src/ol/iview.js
@@ -6,8 +6,9 @@ goog.require('ol.IView3D');


 /**
- * Interface for views. Currently {@link ol.View2D} is implemented.
+ * Interface for views.
 * @interface
+ * @extends {goog.events.Listenable}
 */
 ol.IView = function() {
 };
--- a/src/ol/iview2d.js
+++ b/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() {
 };
--- a/src/ol/layer/heatmaplayer.js
+++ b/src/ol/layer/heatmaplayer.js
@@ -23,7 +23,7 @@ ol.layer.HeatmapLayerProperty = {
 /**
 * @constructor
 * @extends {ol.layer.Vector}
- * @fires {@link ol.render.Event} ol.render.Event
+ * @fires ol.render.Event
 * @param {olx.layer.HeatmapOptions=} opt_options Options.
 * @todo api
 */
--- a/src/ol/layer/imagelayer.js
+++ b/src/ol/layer/imagelayer.js
@@ -7,7 +7,7 @@ goog.require('ol.layer.Layer');
 /**
 * @constructor
 * @extends {ol.layer.Layer}
- * @fires {@link ol.render.Event} ol.render.Event
+ * @fires ol.render.Event
 * @param {olx.layer.LayerOptions} options Layer options.
 * @todo api
 */
--- a/src/ol/layer/layer.js
+++ b/src/ol/layer/layer.js
@@ -12,16 +12,8 @@ goog.require('ol.source.Source');
 /**
 * @constructor
 * @extends {ol.layer.Base}
- * @fires {@link ol.render.Event} ol.render.Event
+ * @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) {
--- a/src/ol/layer/layerbase.js
+++ b/src/ol/layer/layerbase.js
@@ -41,8 +41,7 @@ ol.layer.LayerState;


 /**
- * Base class for all layers. The most basic implementation is
- * {@link ol.layer.Layer}. See {@link ol.layer} for all implementations.
+ * Base class for all layers.
 * @constructor
 * @extends {ol.Object}
 * @param {olx.layer.BaseOptions} options Layer options.
@@ -78,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() {
@@ -92,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() {
@@ -106,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() {
@@ -163,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() {
@@ -177,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() {
@@ -191,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() {
@@ -205,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() {
@@ -225,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() {
@@ -256,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) {
@@ -273,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) {
@@ -288,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) {
@@ -301,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) {
@@ -314,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) {
@@ -327,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) {
@@ -345,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) {
@@ -358,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) {
--- a/src/ol/layer/layergroup.js
+++ b/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);
--- a/src/ol/layer/tilelayer.js
+++ b/src/ol/layer/tilelayer.js
@@ -16,9 +16,8 @@ ol.layer.TileProperty = {
 /**
 * @constructor
 * @extends {ol.layer.Layer}
- * @fires {@link ol.render.Event} ol.render.Event
+ * @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);
--- a/src/ol/layer/vectorlayer.js
+++ b/src/ol/layer/vectorlayer.js
@@ -19,7 +19,7 @@ ol.layer.VectorProperty = {
 *
 * @constructor
 * @extends {ol.layer.Layer}
- * @fires {@link ol.render.Event} ol.render.Event
+ * @fires ol.render.Event
 * @param {olx.layer.VectorOptions=} opt_options Options.
 * @todo api
 */
--- a/src/ol/map.js
+++ b/src/ol/map.js
@@ -156,15 +156,9 @@ ol.MapProperty = {
 * @constructor
 * @extends {ol.Object}
 * @param {olx.MapOptions} options Map options.
- * @fires {@link ol.MapBrowserEvent} ol.MapBrowserEvent
- * @fires {@link ol.MapEvent} ol.MapEvent
- * @fires {@link ol.render.Event} ol.render.Event
- * @todo observable layergroup {ol.layer.Group} a layer group containing the
- *       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
+ * @fires ol.MapBrowserEvent
+ * @fires ol.MapEvent
+ * @fires ol.render.Event
 * @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() {
@@ -662,13 +658,12 @@ ol.Map.prototype.getOverlays = function() {


 /**
- * Gets the collection of
- * {@link ol.interaction|ol.interaction.Interaction} instances
- * associated with this map.  Modifying this collection
- * changes the interactions associated with the map.
+ * Gets the collection of {@link ol.interaction.Interaction} instances
+ * associated with this map. Modifying this collection changes the interactions
+ * associated with the map.
 *
 * Interactions are used for e.g. pan, zoom and rotate.
- * @return {ol.Collection} Interactions.
+ * @return {ol.Collection} {@link ol.interaction.Interaction Interactions}.
 * @todo api
 */
 ol.Map.prototype.getInteractions = function() {
@@ -678,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() {
@@ -724,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() {
@@ -739,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,
@@ -1256,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) {
@@ -1270,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) {
@@ -1284,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) {
@@ -1297,8 +1300,9 @@ goog.exportProperty(


 /**
- * Set the view for this map. Currently {@link ol.View2D} is implememnted.
- * @param {ol.IView} view View.
+ * Set the view for this map.
+ * @param {ol.IView} view The view that controls this map.
+ * @todo observable
 * @todo api
 */
 ol.Map.prototype.setView = function(view) {
--- a/src/ol/object.js
+++ b/src/ol/object.js
@@ -108,7 +108,7 @@ ol.ObjectAccessor.prototype.transform = function(from, to) {
 * @constructor
 * @extends {ol.Observable}
 * @param {Object.<string, *>=} opt_values Values.
- * @fires {@link ol.ObjectEvent} ol.ObjectEvent
+ * @fires ol.ObjectEvent
 * @todo api
 */
 ol.Object = function(opt_values) {
--- a/src/ol/overlay.js
+++ b/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) {
--- a/src/ol/pixel.js
+++ b/src/ol/pixel.js
@@ -2,6 +2,9 @@ goog.provide('ol.Pixel');


 /**
+ * An array with two elements, representing a pixel. The first element is the
+ * x-coordinate, the second the y-coordinate of the pixel.
 * @typedef {Array.<number>}
+ * @todo api
 */
 ol.Pixel;
--- a/src/ol/source/geojsonsource.js
+++ b/src/ol/source/geojsonsource.js
@@ -8,7 +8,7 @@ goog.require('ol.source.StaticVector');
 /**
 * @constructor
 * @extends {ol.source.StaticVector}
- * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
+ * @fires ol.source.VectorEvent
 * @param {olx.source.GeoJSONOptions=} opt_options Options.
 * @todo api
 */
--- a/src/ol/source/gpxsource.js
+++ b/src/ol/source/gpxsource.js
@@ -8,7 +8,7 @@ goog.require('ol.source.StaticVector');
 /**
 * @constructor
 * @extends {ol.source.StaticVector}
- * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
+ * @fires ol.source.VectorEvent
 * @param {olx.source.GPXOptions=} opt_options Options.
 * @todo api
 */
--- a/src/ol/source/igcsource.js
+++ b/src/ol/source/igcsource.js
@@ -8,7 +8,7 @@ goog.require('ol.source.StaticVector');
 /**
 * @constructor
 * @extends {ol.source.StaticVector}
- * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
+ * @fires ol.source.VectorEvent
 * @param {olx.source.IGCOptions=} opt_options Options.
 * @todo api
 */
--- a/src/ol/source/kmlsource.js
+++ b/src/ol/source/kmlsource.js
@@ -8,7 +8,7 @@ goog.require('ol.source.StaticVector');
 /**
 * @constructor
 * @extends {ol.source.StaticVector}
- * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
+ * @fires ol.source.VectorEvent
 * @param {olx.source.KMLOptions=} opt_options Options.
 * @todo api
 */
--- a/src/ol/source/osmxmlsource.js
+++ b/src/ol/source/osmxmlsource.js
@@ -8,7 +8,7 @@ goog.require('ol.source.StaticVector');
 /**
 * @constructor
 * @extends {ol.source.StaticVector}
- * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
+ * @fires ol.source.VectorEvent
 * @param {olx.source.OSMXMLOptions=} opt_options Options.
 * @todo api
 */
--- a/src/ol/source/source.js
+++ b/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,
--- a/src/ol/source/staticvectorsource.js
+++ b/src/ol/source/staticvectorsource.js
@@ -8,7 +8,7 @@ goog.require('ol.source.State');
 /**
 * @constructor
 * @extends {ol.source.FormatVector}
- * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
+ * @fires ol.source.VectorEvent
 * @param {olx.source.StaticVectorOptions} options Options.
 * @todo api
 */
--- a/src/ol/source/topojsonsource.js
+++ b/src/ol/source/topojsonsource.js
@@ -8,7 +8,7 @@ goog.require('ol.source.StaticVector');
 /**
 * @constructor
 * @extends {ol.source.StaticVector}
- * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
+ * @fires ol.source.VectorEvent
 * @param {olx.source.TopoJSONOptions=} opt_options Options.
 * @todo api
 */
--- a/src/ol/source/vectorsource.js
+++ b/src/ol/source/vectorsource.js
@@ -41,7 +41,7 @@ ol.source.VectorEventType = {
 /**
 * @constructor
 * @extends {ol.source.Source}
- * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
+ * @fires ol.source.VectorEvent
 * @param {olx.source.VectorOptions=} opt_options Vector source options.
 * @todo api
 */
--- a/src/ol/view2d.js
+++ b/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) {