Greatly simplify and document the usage of JSDoc

This commit simplifies the exports.js plugin so it only relies on the stability notes to generate the documentation, which completely decouples it from the exportable API. As a rule of thumb, whenever something has an 'api' annotation, it should also have a 'stability' annotation. A more verbose documentation of ol3 specific annotation usage is available in the new 'apidoc/readme.md' file. This commit also modifies all source files to implement these usage suggestions.
2014-04-13 10:43:05 +02:00
parent aaf6101d0f
commit c17ac0cae3
84 changed files with 403 additions and 195 deletions
--- a/apidoc/conf.json
+++ b/apidoc/conf.json
@@ -22,7 +22,8 @@
        "node_modules/jsdoc/plugins/markdown",
        "apidoc/plugins/inheritdoc",
        "apidoc/plugins/interface",
-        "apidoc/plugins/exports",
+        "apidoc/plugins/api",
+        "apidoc/plugins/olx-typedefs",
        "apidoc/plugins/todo",
        "apidoc/plugins/observable",
        "apidoc/plugins/stability"
--- a/apidoc/plugins/api.js
+++ b/apidoc/plugins/api.js
@@ -0,0 +1,51 @@
+/*
+ * Based on @stability annotations, and assuming that items with no @stability
+ * annotation should not be documented, this plugin removes undocumented symbols
+ * from the documentation. Undocumented classes with documented members get a
+ * 'hideConstructur' property, which is read by the template so it can hide the
+ * constructor.
+ */
+
+function hasApiMembers(doclet) {
+  return doclet.longname.split('#')[0] == this.longname;
+}
+
+var api = [];
+
+exports.handlers = {
+
+  newDoclet: function(e) {
+    var doclet = e.doclet;
+    // Keep track of api items - needed in parseComplete to determine classes
+    // with api members.
+    if (doclet.stability) {
+      api.push(doclet);
+    }
+    // Mark explicity defined namespaces - needed in parseComplete to keep
+    // namespaces that we need as containers for api items.
+    if (/.*\.jsdoc$/.test(doclet.meta.filename) && doclet.kind == 'namespace') {
+      doclet.namespace_ = true;
+    }
+  },
+
+  parseComplete: function(e) {
+    var doclets = e.doclets;
+    for (var i = doclets.length - 1; i >= 0; --i) {
+      var doclet = doclets[i];
+      // Always document namespaces and items with stability annotation
+      if (doclet.stability || doclet.namespace_) {
+        continue;
+      }
+      if (doclet.kind == 'class' && api.some(hasApiMembers, doclet)) {
+        // Mark undocumented classes with documented members as unexported.
+        // This is used in ../template/tmpl/container.tmpl to hide the
+        // constructor from the docs.
+        doclet.hideConstructor = true;
+      } else {
+        // Remove all other undocumented symbols
+        doclets.splice(i, 1);
+      }
+    }
+  }
+
+};
--- a/apidoc/plugins/exports.js
+++ b/apidoc/plugins/exports.js
@@ -1,109 +0,0 @@
-/*
- * This plugin removes unexported symbols from the documentation.
- * Unexported modules linked from @param or @fires will be marked unexported,
- * and the documentation will not contain the constructor. Everything else is
- * marked undocumented, which will remove it from the docs.
- */
-
-var api = [];
-var unexported = [];
-var observablesByClass = {};
-
-function collectExports(source) {
-  var symbols = JSON.parse(source).symbols;
-  for (var i = 0, ii = symbols.length; i < ii; ++i) {
-    api.push(symbols[i].name);
-  }
-}
-
-var encoding = env.conf.encoding || 'utf8';
-var fs = require('jsdoc/fs');
-collectExports(fs.readFileSync('build/symbols.json', encoding));
-
-
-exports.handlers = {
-  
-  newDoclet: function(e) {
-    var i, ii, j, jj;
-    if (e.doclet.meta.filename == "olx.js" && e.doclet.longname != 'olx') {
-      api.push(e.doclet.longname);
-    }
-    if (e.doclet.longname.indexOf('oli.') === 0) {
-      unexported.push(e.doclet.longname.replace(/^oli\./, 'ol.'));
-    }
-    if (api.indexOf(e.doclet.longname) > -1) {
-      var names, name;
-      var params = e.doclet.params;
-      if (params) {
-        for (i = 0, ii = params.length; i < ii; ++i) {
-          names = params[i].type.names;
-          if (names) {
-            for (j = 0, jj=names.length; j < jj; ++j) {
-              name = names[j];
-              if (unexported.indexOf(name) === -1) {
-                unexported.push(name);
-              }
-            }
-          }
-        }
-      }
-      var links = e.doclet.comment.match(/\{@link ([^\}]*)\}/g);
-      if (links) {
-        for (i=0, ii=links.length; i < ii; ++i) {
-          var link = links[i].match(/\{@link (.*)\}/)[1];
-          if (unexported.indexOf(link) === -1) {
-            unexported.push(link);
-          }
-        }
-      }
-    }
-    if (e.doclet.observables) {
-      var observables = observablesByClass[e.doclet.longname] = [];
-      for (i = e.doclet.observables.length - 1; i >= 0; --i) {
-         observables.push(e.doclet.observables[i].name);
-      }
-    }
-  },
-  
-  parseComplete: function(e) {
-    for (var j = e.doclets.length - 1; j >= 0; --j) {
-      var doclet = e.doclets[j];
-      if (doclet.meta.filename == 'olx.js' && doclet.kind == 'typedef') {
-        for (var i = e.doclets.length - 1; i >= 0; --i) {
-          var propertyDoclet = e.doclets[i];
-          if (propertyDoclet.memberof == doclet.longname) {
-            if (!doclet.properties) {
-              doclet.properties = [];
-            }
-            doclet.properties.unshift(propertyDoclet);
-            e.doclets.splice(i, 1);
-          }
-        }
-      }
-      if (doclet.kind == 'namespace' || doclet.kind == 'event' || doclet.fires) {
-        continue;
-      }
-      var fqn = doclet.longname;
-      if (fqn) {
-        var getterOrSetter = fqn.match(/([^#]*)#[gs]et(.*)/);
-        if (getterOrSetter) {
-          var observables = observablesByClass[getterOrSetter[1]];
-          if (observables && observables.indexOf(getterOrSetter[2].toLowerCase()) > -1) {
-            // Always document getters/setters of observables
-            continue;
-          }
-        }
-        if (doclet.memberof && doclet.memberof.indexOf('oli.') === 0 &&
-            unexported.indexOf(doclet.memberof) > -1) {
-          // Always document members of referenced oli interfaces
-          continue;
-        }
-        doclet.unexported = (api.indexOf(fqn) === -1 && unexported.indexOf(fqn) !== -1);
-        if (api.indexOf(fqn) === -1 && unexported.indexOf(fqn) === -1) {
-          e.doclets.splice(j, 1);
-        }
-      }
-    }
-  }
-
-};
--- a/apidoc/plugins/interface.js
+++ b/apidoc/plugins/interface.js
@@ -10,13 +10,16 @@ exports.defineTags = function(dictionary) {
    }
  });

+  var augmentsTag = dictionary.lookUp('augments');
  dictionary.defineTag('implements', {
    mustHaveValue: true,
    onTagged: function(doclet, tag) {
+      tag.value = tag.value.match(/^\{?([^\}]*)\}?$/)[1];
+      augmentsTag.onTagged.apply(this, arguments);
      if (!doclet.implements) {
        doclet.implements = [];
      }
-      doclet.implements.push(tag.value.match(/^{(.*)}$/)[1]);
+      doclet.implements.push(tag.value);
    }
  });

--- a/apidoc/plugins/olx-typedefs.js
+++ b/apidoc/plugins/olx-typedefs.js
@@ -0,0 +1,23 @@
+/*
+ * Converts olx.js @type annotations into properties of the previous @typedef.
+ */
+
+var olxTypedef = null;
+
+exports.handlers = {
+
+  newDoclet: function(e) {
+    var doclet = e.doclet;
+    if (doclet.meta.filename == 'olx.js') {
+      if (doclet.kind == 'typedef') {
+        olxTypedef = doclet;
+        doclet.properties = [];
+      } else if (olxTypedef && doclet.memberof == olxTypedef.longname) {
+        olxTypedef.properties.push(doclet);
+      } else {
+        olxTypedef = null;
+      }
+    }
+  }
+
+};
--- a/apidoc/readme.md
+++ b/apidoc/readme.md
@@ -0,0 +1,136 @@
+# API Documentation
+
+This directory contains configuration (`conf.json`), static content (`index.md`), template (`template/`) and plugins (`plugins/`) for the [JSDoc3](http://usejsdoc.org/) API generator.
+
+## Documenting the source code
+
+JSDoc annotations are used for metadata used by the compiler, for defining the user facing API, and for user documentation.
+
+In the simplest case, a JSDoc block can look like this:
+```js
+/**
+ * Add the given control to the map.
+ * @param {ol.control.Control} control Control.
+ * @todo stability experimental
+ * @todo api
+ */
+ol.Map.prototype.addControl = function(control) {
+  // ...
+};
+```
+The first line is text for the user documentation. This can be long, and it can
+contain Markdown.
+
+The second line tells the Closure compiler the type of the argument.
+
+The third line marks the API stability. Once the documentation story is fully settled, we will remove the `todo ` and just write `@stability experimental`. Without such a stability note, the method will not be documented in the generated API documentation.
+
+The last line marks the method as exportable so it can be made available to the user facing API. This will also change to just `@api` eventually.
+
+### Observable properties
+
+For classes that inherit from `ol.Object`, there is a special documentation case for getters and setters:
+```js
+/**
+ * Get the size of this map.
+ * @return {ol.Size|undefined} Size.
+ * @todo stability experimental
+ */
+ol.Map.prototype.getSize = function() {
+  // ...
+};
+goog.exportProperty(
+    ol.Map.prototype,
+    'getSize',
+    ol.Map.prototype.getSize);
+```
+Because `ol.Object` needs to rely on these getter and setter names, these methods are not marked `@api` as exportable. Instead, `goog.exportProperty()` is used after the method definition to make sure that this method is always part of the API and not renamed in build configurations that do not need it.
+
+To document observable properties with the `ol.ObjectEvent` types they are associated with, the `@observable` property is used (currently still `@todo observable`):
+```js
+ * @constructor
+ * @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
+ */
+ol.Map = function(options) {
+```
+The first argument to that annotation is the name of the property, then the type(s) in curly braces, and then a description. NOTE/TODO: The `apidoc/plugins/observable.js` plugin does currently not handle inherited observable properties.
+
+### Events
+
+Events are documented using `@fires` and `@event` annotations:
+```js
+/**
+ * Constants for event names.
+ * @enum {string}
+ */
+ol.MapBrowserEvent.EventType = {
+  /**
+   * A true single click with no dragging and no double click. Note that this
+   * event is delayed by 250 ms to ensure that it is not a double click.
+   * @event ol.MapBrowserEvent#singleclick
+   * @todo stability experimental
+   */
+  SINGLECLICK: 'singleclick',
+  // ...
+};
+```
+Note the value of the `@event` annotation. The text before the hash refers to the event class that the event belongs to, and the text after the hash is the type of the event. To export these properties, they need to be defined in `externs/oli.js` (also see `readme.md` in `externs/`). In addition, a stability note is required in the source code (`src/ol/MapBrowserEvent.js`) to make sure that documentation gets generated:
+```js
+ol.MapBrowserEvent = function(type, map, browserEvent, opt_frameState) {
+
+  // ...
+
+  /**
+   * @type {ol.Coordinate}
+   * @todo stability experimental
+   */
+  this.coordinate = map.getEventCoordinate(this.originalEvent);
+
+  // ...
+
+};
+```
+To document which events are fired by a class or method, the `@fires` annotation is used:
+```js
+ * @fires {@link ol.MapBrowserEvent} ol.MapBrowserEvent
+ * @fires {@link ol.MapEvent} ol.MapEvent
+ * @fires {@link ol.render.Event} ol.render.Event
+ */
+ol.Map = function(options) {
+  // ...
+};
+```
+Again, note the syntax of the `@fires` annotation. The link is necessary to provide a link to the documentation of the event, and the name of the event class is necessary for JSDoc3 to know which event we are talking about.
+
+### Special cases with inheritance
+
+When an item is marked `@api` in a subclass and not the base class, the documentation needs to be provided in the class where the item is exported. If the item is a (member) function, the `@function` annotation needs to be used:
+```js
+/**
+ * Read a feature from a GeoJSON Feature source.  This method will throw
+ * an error if used with a FeatureCollection source.
+ * @function
+ * @param {ArrayBuffer|Document|Node|Object|string} source Source.
+ * @return {ol.Feature} Feature.
+ * @todo stability experimental
+ * @todo api
+ */
+ol.format.GeoJSON.prototype.readFeature;
+```
+The `@function` annotation is also needed when the function assignment is a
+constant function from a `goog` namespace (e.g. `goog.AbstractMethod`).
+
+For an abstract method, if it exported by every subclass, the documentation can be provided in the abstract class, with a `@stability` note. Implementing classes can use `@inheritDoc` and export the item:
+```js
+/**
+ * @inheritDoc
+ * @todo api
+ */
+```
+When only a subset of the subclasses exports the item, @inheritDoc cannot
+be used, and every exporting class needs to provide the documentation.
--- a/apidoc/template/tmpl/container.tmpl
+++ b/apidoc/template/tmpl/container.tmpl
@@ -27,7 +27,7 @@
    <?js if (doc.kind === 'module' && doc.module) { ?>
        <?js= self.partial('method.tmpl', doc.module) ?>
    <?js } ?>
-    <?js if (!doc.unexported && doc.kind === 'class') { ?>
+    <?js if (doc.kind === 'class' && !doc.hideConstructor && !doc.interface) { ?>
        <?js= self.partial('method.tmpl', doc) ?>
    <?js } else { ?>
        <?js if (doc.description) { ?>
@@ -47,7 +47,8 @@
        <h3 class="subsection-title">Extends</h3>
        
        <ul><?js doc.augments.forEach(function(a) { ?>
-            <li><?js= self.linkto(a, a) ?></li>
+            <li><?js= self.linkto(a, a) ?>
+              <?js= (doc.implements&&doc.implements.indexOf(a)>-1?'(Interface)':'') ?></li>
        <?js }); ?></ul>
    <?js } ?>
    
--- a/externs/oli.js
+++ b/externs/oli.js
@@ -77,7 +77,10 @@ oli.FrameState.prototype.layerStatesArray;
 oli.FrameState.prototype.logos;


-/** @type {number} */
+/**
+ * @type {number}
+ * @todo stability experimental
+ */
 oli.FrameState.prototype.pixelRatio;


@@ -101,7 +104,10 @@ oli.FrameState.prototype.skippedFeatureUids_;
 oli.FrameState.prototype.tileQueue;


-/** @type {number} */
+/**
+ * @type {number}
+ * @todo stability experimental
+ */
 oli.FrameState.prototype.time;


@@ -109,7 +115,10 @@ oli.FrameState.prototype.time;
 oli.FrameState.prototype.usedTiles;


-/** @type {oli.View2DState} */
+/**
+ * @type {oli.View2DState}
+ * @todo stability experimental
+ */
 oli.FrameState.prototype.view2DState;


--- a/src/ol/browserfeature.js
+++ b/src/ol/browserfeature.js
@@ -87,7 +87,6 @@ ol.BrowserFeature.DEVICE_PIXEL_RATIO = goog.global.devicePixelRatio || 1;
 * True if the browser supports ArrayBuffers.
 * @const
 * @type {boolean}
- * @todo stability experimental
 */
 ol.BrowserFeature.HAS_ARRAY_BUFFER = 'ArrayBuffer' in goog.global;

@@ -95,7 +94,6 @@ ol.BrowserFeature.HAS_ARRAY_BUFFER = 'ArrayBuffer' in goog.global;
 /**
 * True if the browser's Canvas implementation implements {get,set}LineDash.
 * @type {boolean}
- * @todo stability experimental
 */
 ol.BrowserFeature.HAS_CANVAS_LINE_DASH = false;

@@ -146,7 +144,6 @@ ol.BrowserFeature.HAS_DEVICE_ORIENTATION =
 * True if browser supports DOM.
 * @const
 * @type {boolean}
- * @todo stability experimental
 */
 ol.BrowserFeature.HAS_DOM = ol.ENABLE_DOM;

@@ -164,7 +161,6 @@ ol.BrowserFeature.HAS_GEOLOCATION = 'geolocation' in goog.global.navigator;
 /**
 * @const
 * @type {boolean}
- * @todo stability experimental
 */
 ol.BrowserFeature.HAS_JSON_PARSE =
    'JSON' in goog.global && 'parse' in goog.global.JSON;
@@ -184,7 +180,6 @@ ol.BrowserFeature.HAS_TOUCH = ol.ASSUME_TOUCH || 'ontouchstart' in goog.global;
 * True if browser supports pointer events.
 * @const
 * @type {boolean}
- * @todo stability experimental
 */
 ol.BrowserFeature.HAS_POINTER = 'PointerEvent' in goog.global;

@@ -193,7 +188,6 @@ ol.BrowserFeature.HAS_POINTER = 'PointerEvent' in goog.global;
 * True if browser supports ms pointer events (IE 10).
 * @const
 * @type {boolean}
- * @todo stability experimental
 */
 ol.BrowserFeature.HAS_MSPOINTER =
    !!(goog.global.navigator.msPointerEnabled);
@@ -203,7 +197,6 @@ ol.BrowserFeature.HAS_MSPOINTER =
 * True if browser supports WebGL.
 * @const
 * @type {boolean}
- * @todo stability experimental
 */
 ol.BrowserFeature.HAS_WEBGL = ol.ENABLE_WEBGL && (
    /**
--- a/src/ol/color/color.js
+++ b/src/ol/color/color.js
@@ -103,6 +103,7 @@ ol.color.blend = function(dst, src, opt_color) {
 /**
 * @param {ol.Color|string} color Color.
 * @return {ol.Color} Color.
+ * @todo stability experimental
 * @todo api
 */
 ol.color.asArray = function(color) {
@@ -118,6 +119,7 @@ ol.color.asArray = function(color) {
 /**
 * @param {ol.Color|string} color Color.
 * @return {string} String.
+ * @todo stability experimental
 * @todo api
 */
 ol.color.asString = function(color) {
--- a/src/ol/control/mousepositioncontrol.js
+++ b/src/ol/control/mousepositioncontrol.js
@@ -38,11 +38,11 @@ ol.control.MousePositionProperty = {
 * @extends {ol.control.Control}
 * @param {olx.control.MousePositionOptions=} opt_options Mouse position
 *     options.
- * @todo stability experimental
 * @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 stability experimental
 * @todo api
 */
 ol.control.MousePosition = function(opt_options) {
--- a/src/ol/control/scalelinecontrol.js
+++ b/src/ol/control/scalelinecontrol.js
@@ -49,9 +49,9 @@ ol.control.ScaleLineUnits = {
 * @constructor
 * @extends {ol.control.Control}
 * @param {olx.control.ScaleLineOptions=} opt_options Scale line options.
- * @todo stability experimental
 * @todo observable units {ol.control.ScaleLineUnits} the units to use in the
 *       scale line
+ * @todo stability experimental
 * @todo api
 */
 ol.control.ScaleLine = function(opt_options) {
--- a/src/ol/coordinate.js
+++ b/src/ol/coordinate.js
@@ -36,6 +36,7 @@ ol.CoordinateArray;
 * @param {ol.Coordinate} coordinate Coordinate.
 * @param {ol.Coordinate} delta Delta.
 * @return {ol.Coordinate} Coordinate.
+ * @todo stability experimental
 * @todo api
 */
 ol.coordinate.add = function(coordinate, delta) {
@@ -161,6 +162,7 @@ ol.coordinate.equals = function(coordinate1, coordinate2) {
 * @param {ol.Coordinate} coordinate Coordinate.
 * @param {number} angle Angle.
 * @return {ol.Coordinate} Coordinate.
+ * @todo stability experimental
 * @todo api
 */
 ol.coordinate.rotate = function(coordinate, angle) {
--- a/src/ol/deviceorientation.js
+++ b/src/ol/deviceorientation.js
@@ -69,7 +69,6 @@ ol.DeviceOrientationProperty = {
 * @constructor
 * @extends {ol.Object}
 * @param {olx.DeviceOrientationOptions=} opt_options Options.
- * @todo stability experimental
 * @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
@@ -80,6 +79,7 @@ ol.DeviceOrientationProperty = {
 *       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 stability experimental
 * @todo api
 */
 ol.DeviceOrientation = function(opt_options) {
--- a/src/ol/dom/input.js
+++ b/src/ol/dom/input.js
@@ -29,9 +29,9 @@ ol.dom.InputProperty = {
 * @constructor
 * @extends {ol.Object}
 * @param {Element} target Target element.
- * @todo stability experimental
 * @todo observable value {string} the value of the Input
 * @todo observable checked {boolean} the checked state of the Input
+ * @todo stability experimental
 * @todo api
 */
 ol.dom.Input = function(target) {
--- a/src/ol/easing.js
+++ b/src/ol/easing.js
@@ -7,6 +7,7 @@ goog.require('goog.fx.easing');
 * from https://raw.github.com/DmitryBaranovskiy/raphael/master/raphael.js
 * @param {number} t Input between 0 and 1.
 * @return {number} Output between 0 and 1.
+ * @todo stability experimental
 * @todo api
 */
 ol.easing.bounce = function(t) {
@@ -34,6 +35,7 @@ ol.easing.bounce = function(t) {
 /**
 * @param {number} t Input between 0 and 1.
 * @return {number} Output between 0 and 1.
+ * @todo stability experimental
 * @todo api
 */
 ol.easing.easeIn = goog.fx.easing.easeIn;
@@ -42,6 +44,7 @@ ol.easing.easeIn = goog.fx.easing.easeIn;
 /**
 * @param {number} t Input between 0 and 1.
 * @return {number} Output between 0 and 1.
+ * @todo stability experimental
 * @todo api
 */
 ol.easing.easeOut = goog.fx.easing.easeOut;
@@ -51,6 +54,7 @@ ol.easing.easeOut = goog.fx.easing.easeOut;
 * from https://raw.github.com/DmitryBaranovskiy/raphael/master/raphael.js
 * @param {number} t Input between 0 and 1.
 * @return {number} Output between 0 and 1.
+ * @todo stability experimental
 * @todo api
 */
 ol.easing.elastic = function(t) {
@@ -61,6 +65,7 @@ ol.easing.elastic = function(t) {
 /**
 * @param {number} t Input between 0 and 1.
 * @return {number} Output between 0 and 1.
+ * @todo stability experimental
 * @todo api
 */
 ol.easing.inAndOut = goog.fx.easing.inAndOut;
@@ -69,6 +74,7 @@ ol.easing.inAndOut = goog.fx.easing.inAndOut;
 /**
 * @param {number} t Input between 0 and 1.
 * @return {number} Output between 0 and 1.
+ * @todo stability experimental
 * @todo api
 */
 ol.easing.linear = function(t) {
@@ -79,6 +85,7 @@ ol.easing.linear = function(t) {
 /**
 * @param {number} t Input between 0 and 1.
 * @return {number} Output between 0 and 1.
+ * @todo stability experimental
 * @todo api
 */
 ol.easing.upAndDown = function(t) {
--- a/src/ol/events/condition.js
+++ b/src/ol/events/condition.js
@@ -71,7 +71,6 @@ ol.events.condition.never = goog.functions.FALSE;
 /**
 * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
 * @return {boolean} True if the event is a `singleclick` event.
- * @todo stability experimental
 */
 ol.events.condition.singleClick = function(mapBrowserEvent) {
  return mapBrowserEvent.type == ol.MapBrowserEvent.EventType.SINGLECLICK;
@@ -143,7 +142,6 @@ ol.events.condition.targetNotEditable = function(mapBrowserEvent) {
 /**
 * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
 * @return {boolean} True if the event originates from a mouse device.
- * @todo stability experimental
 */
 ol.events.condition.mouseOnly = function(mapBrowserEvent) {
  goog.asserts.assertInstanceof(mapBrowserEvent, ol.MapBrowserPointerEvent);
--- a/src/ol/extent.js
+++ b/src/ol/extent.js
@@ -54,7 +54,6 @@ ol.extent.boundingExtent = function(coordinates) {
 * @param {ol.Extent=} opt_extent Destination extent.
 * @private
 * @return {ol.Extent} Extent.
- * @todo stability experimental
 */
 ol.extent.boundingExtentXYs_ = function(xs, ys, opt_extent) {
  goog.asserts.assert(xs.length > 0);
@@ -73,6 +72,7 @@ ol.extent.boundingExtentXYs_ = function(xs, ys, opt_extent) {
 * @param {number} value The amount by wich the extent should be buffered.
 * @param {ol.Extent=} opt_extent Extent.
 * @return {ol.Extent} Extent.
+ * @todo stability experimental
 * @todo api
 */
 ol.extent.buffer = function(extent, value, opt_extent) {
@@ -99,7 +99,6 @@ ol.extent.buffer = function(extent, value, opt_extent) {
 * @param {ol.Extent} extent Extent to clone.
 * @param {ol.Extent=} opt_extent Extent.
 * @return {ol.Extent} The clone.
- * @todo stability experimental
 */
 ol.extent.clone = function(extent, opt_extent) {
  if (goog.isDef(opt_extent)) {
@@ -219,7 +218,6 @@ ol.extent.createEmpty = function() {
 * @param {number} maxY Maximum Y.
 * @param {ol.Extent=} opt_extent Destination extent.
 * @return {ol.Extent} Extent.
- * @todo stability experimental
 */
 ol.extent.createOrUpdate = function(minX, minY, maxX, maxY, opt_extent) {
  if (goog.isDef(opt_extent)) {
@@ -298,7 +296,6 @@ ol.extent.createOrUpdateFromRings = function(rings, opt_extent) {
 * Empties extent in place.
 * @param {ol.Extent} extent Extent.
 * @return {ol.Extent} Extent.
- * @todo stability experimental
 */
 ol.extent.empty = function(extent) {
  extent[0] = extent[1] = Infinity;
@@ -347,7 +344,6 @@ ol.extent.extend = function(extent1, extent2) {
 /**
 * @param {ol.Extent} extent Extent.
 * @param {ol.Coordinate} coordinate Coordinate.
- * @todo stability experimental
 */
 ol.extent.extendCoordinate = function(extent, coordinate) {
  if (coordinate[0] < extent[0]) {
@@ -487,7 +483,6 @@ ol.extent.getEnlargedArea = function(extent1, extent2) {
 * @param {ol.Size} size Size.
 * @param {ol.Extent=} opt_extent Destination extent.
 * @return {ol.Extent} Extent.
- * @todo stability experimental
 */
 ol.extent.getForView2DAndSize =
    function(center, resolution, rotation, size, opt_extent) {
@@ -617,7 +612,6 @@ ol.extent.isEmpty = function(extent) {
 /**
 * @param {ol.Extent} extent Extent.
 * @return {boolean} Is infinite.
- * @todo stability experimental
 */
 ol.extent.isInfinite = function(extent) {
  return extent[0] == -Infinity || extent[1] == -Infinity ||
@@ -629,7 +623,6 @@ ol.extent.isInfinite = function(extent) {
 * @param {ol.Extent} extent Extent.
 * @param {ol.Coordinate} coordinate Coordinate.
 * @return {ol.Coordinate} Coordinate.
- * @todo stability experimental
 */
 ol.extent.normalize = function(extent, coordinate) {
  return [
@@ -660,7 +653,6 @@ ol.extent.returnOrUpdate = function(extent, opt_extent) {
 /**
 * @param {ol.Extent} extent Extent.
 * @param {number} value Value.
- * @todo stability experimental
 */
 ol.extent.scaleFromCenter = function(extent, value) {
  var deltaX = ((extent[2] - extent[0]) / 2) * (value - 1);
@@ -729,7 +721,6 @@ ol.extent.segmentIntersects = function(extent, start, end) {
 * @param {ol.Extent} extent1 Extent 1.
 * @param {ol.Extent} extent2 Extent 2.
 * @return {boolean} Touches.
- * @todo stability experimental
 */
 ol.extent.touches = function(extent1, extent2) {
  var intersects = ol.extent.intersects(extent1, extent2);
--- a/src/ol/feature.js
+++ b/src/ol/feature.js
@@ -231,7 +231,6 @@ ol.feature.FeatureStyleFunction;
 * @param {number} resolution Resolution.
 * @return {Array.<ol.style.Style>} Style.
 * @this {ol.Feature}
- * @todo stability experimental
 */
 ol.feature.defaultFeatureStyleFunction = function(resolution) {
  var fill = new ol.style.Fill({
@@ -280,7 +279,6 @@ ol.feature.StyleFunction;
 * @param {ol.Feature} feature Feature.
 * @param {number} resolution Resolution.
 * @return {Array.<ol.style.Style>} Style.
- * @todo stability experimental
 */
 ol.feature.defaultStyleFunction = function(feature, resolution) {
  var featureStyleFunction = feature.getStyleFunction();
@@ -361,7 +359,6 @@ ol.feature.createStyleFunction = function(obj) {
 /**
 * Default styles for editing features.
 * @return {Object.<ol.geom.GeometryType, Array.<ol.style.Style>>} Styles
- * @todo stability experimental
 */
 ol.feature.createDefaultEditingStyles = function() {
  /** @type {Object.<ol.geom.GeometryType, Array.<ol.style.Style>>} */
--- a/src/ol/featureoverlay.js
+++ b/src/ol/featureoverlay.js
@@ -265,6 +265,7 @@ ol.FeatureOverlay.prototype.setStyle = function(style) {
 * option at construction or to the `setStyle` method.
 * @return {ol.style.Style|Array.<ol.style.Style>|ol.feature.StyleFunction}
 *     Overlay style.
+ * @todo stability experimental
 * @todo api
 */
 ol.FeatureOverlay.prototype.getStyle = function() {
@@ -275,6 +276,7 @@ ol.FeatureOverlay.prototype.getStyle = function() {
 /**
 * Get the style function.
 * @return {ol.feature.StyleFunction|undefined} Style function.
+ * @todo stability experimental
 * @todo api
 */
 ol.FeatureOverlay.prototype.getStyleFunction = function() {
--- a/src/ol/format/geojsonformat.js
+++ b/src/ol/format/geojsonformat.js
@@ -323,6 +323,7 @@ ol.format.GeoJSON.prototype.getExtensions = function() {
 * @function
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {ol.Feature} Feature.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.GeoJSON.prototype.readFeature;
@@ -335,6 +336,7 @@ ol.format.GeoJSON.prototype.readFeature;
 * @function
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {Array.<ol.Feature>} Features.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.GeoJSON.prototype.readFeatures;
@@ -389,6 +391,7 @@ ol.format.GeoJSON.prototype.readFeaturesFromObject = function(object) {
 * @function
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {ol.geom.Geometry} Geometry.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.GeoJSON.prototype.readGeometry;
@@ -408,6 +411,7 @@ ol.format.GeoJSON.prototype.readGeometryFromObject = function(object) {
 *
 * @param {ArrayBuffer|Document|Node|Object|string} object Source.
 * @return {ol.proj.Projection} Projection.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.GeoJSON.prototype.readProjection = function(object) {
@@ -438,6 +442,7 @@ ol.format.GeoJSON.prototype.readProjection = function(object) {
 * @function
 * @param {ol.Feature} feature Feature.
 * @return {ArrayBuffer|Node|Object|string} Result.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.GeoJSON.prototype.writeFeature;
@@ -474,6 +479,7 @@ ol.format.GeoJSON.prototype.writeFeatureObject = function(feature) {
 * @function
 * @param {Array.<ol.Feature>} features Features.
 * @return {ArrayBuffer|Node|Object|string} Result.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.GeoJSON.prototype.writeFeatures;
--- a/src/ol/format/gmlformat.js
+++ b/src/ol/format/gmlformat.js
@@ -29,7 +29,6 @@ goog.require('ol.xml');
 * @param {olx.format.GMLOptions=} opt_options
 *     Optional configuration object.
 * @extends {ol.format.XMLFeature}
- * @todo stability experimental
 */
 ol.format.GML = function(opt_options) {
  var options = /** @type {olx.format.GMLOptions} */
--- a/src/ol/format/gpxformat.js
+++ b/src/ol/format/gpxformat.js
@@ -370,6 +370,7 @@ ol.format.GPX.WPT_PARSERS_ = ol.xml.makeParsersNS(
 * @function
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {ol.Feature} Feature.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.GPX.prototype.readFeature;
@@ -401,6 +402,7 @@ ol.format.GPX.prototype.readFeatureFromNode = function(node) {
 * @function
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {Array.<ol.Feature>} Features.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.GPX.prototype.readFeatures;
@@ -433,6 +435,7 @@ ol.format.GPX.prototype.readFeaturesFromNode = function(node) {
 *
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {ol.proj.Projection} Projection.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.GPX.prototype.readProjection;
@@ -795,7 +798,6 @@ ol.format.GPX.GPX_SERIALIZERS_ = ol.xml.makeStructureNS(
 /**
 * @constructor
 * @extends {ol.format.GPX}
- * @todo stability experimental
 */
 ol.format.GPX.V1_1 = function() {
  goog.base(this);
@@ -809,6 +811,7 @@ goog.inherits(ol.format.GPX.V1_1, ol.format.GPX);
 * @function
 * @param {Array.<ol.Feature>} features Features.
 * @return {ArrayBuffer|Node|Object|string} Result.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.GPX.prototype.writeFeatures;
--- a/src/ol/format/igcformat.js
+++ b/src/ol/format/igcformat.js
@@ -92,6 +92,7 @@ ol.format.IGC.prototype.getExtensions = function() {
 * @function
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {ol.Feature} Feature.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.IGC.prototype.readFeature;
@@ -178,6 +179,7 @@ ol.format.IGC.prototype.readFeatureFromText = function(text) {
 * @function
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {Array.<ol.Feature>} Features.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.IGC.prototype.readFeatures;
@@ -202,6 +204,7 @@ ol.format.IGC.prototype.readFeaturesFromText = function(text) {
 * @function
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {ol.proj.Projection} Projection.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.IGC.prototype.readProjection;
--- a/src/ol/format/kmlformat.js
+++ b/src/ol/format/kmlformat.js
@@ -1451,6 +1451,7 @@ ol.format.KML.prototype.readSharedStyleMap_ = function(node, objectStack) {
 * @function
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {ol.Feature} Feature.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.KML.prototype.readFeature;
@@ -1480,6 +1481,7 @@ ol.format.KML.prototype.readFeatureFromNode = function(node) {
 * @function
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {Array.<ol.Feature>} Features.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.KML.prototype.readFeatures;
@@ -1529,7 +1531,6 @@ ol.format.KML.prototype.readFeaturesFromNode = function(node) {
 /**
 * @param {Document|Node|string} source Souce.
 * @return {string|undefined} Name.
- * @todo stability experimental
 */
 ol.format.KML.prototype.readName = function(source) {
  if (ol.xml.isDocument(source)) {
@@ -1599,6 +1600,7 @@ ol.format.KML.prototype.readNameFromNode = function(node) {
 * @function
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {ol.proj.Projection} Projection.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.KML.prototype.readProjection;
--- a/src/ol/format/osmxmlformat.js
+++ b/src/ol/format/osmxmlformat.js
@@ -18,6 +18,7 @@ goog.require('ol.xml');
 /**
 * @constructor
 * @extends {ol.format.XMLFeature}
+ * @todo stability experimental
 * @todo api
 */
 ol.format.OSMXML = function() {
--- a/src/ol/format/topojsonformat.js
+++ b/src/ol/format/topojsonformat.js
@@ -272,6 +272,7 @@ ol.format.TopoJSON.readFeatureFromGeometry_ = function(object, arcs,
 * @function
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {Array.<ol.Feature>} Features.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.TopoJSON.prototype.readFeatures;
@@ -382,6 +383,7 @@ ol.format.TopoJSON.transformVertex_ = function(vertex, scale, translate) {
 * @function
 * @param {ArrayBuffer|Document|Node|Object|string} object Source.
 * @return {ol.proj.Projection} Projection.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.TopoJSON.prototype.readProjection = function(object) {
--- a/src/ol/format/wfsformat.js
+++ b/src/ol/format/wfsformat.js
@@ -93,6 +93,7 @@ ol.format.WFS.prototype.readFeaturesFromNode = function(node) {
 /**
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {ol.format.WFS.TransactionResponse|undefined} Transaction response.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.WFS.prototype.readTransactionResponse = function(source) {
@@ -115,6 +116,7 @@ ol.format.WFS.prototype.readTransactionResponse = function(source) {
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {ol.format.WFS.FeatureCollectionMetadata|undefined}
 *     FeatureCollection metadata.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.WFS.prototype.readFeatureCollectionMetadata = function(source) {
@@ -552,6 +554,7 @@ ol.format.WFS.writeGetFeature_ = function(node, featureTypes, objectStack) {
 /**
 * @param {olx.format.WFSWriteGetFeatureOptions} options Options.
 * @return {Node} Result.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.WFS.prototype.writeGetFeature = function(options) {
@@ -604,6 +607,7 @@ ol.format.WFS.prototype.writeGetFeature = function(options) {
 * @param {Array.<ol.Feature>} deletes The features to delete.
 * @param {olx.format.WFSWriteTransactionOptions} options Write options.
 * @return {Node} Result.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.WFS.prototype.writeTransaction = function(inserts, updates, deletes,
--- a/src/ol/format/wmscapabilitiesformat.js
+++ b/src/ol/format/wmscapabilitiesformat.js
@@ -15,6 +15,7 @@ goog.require('ol.xml');
 /**
 * @constructor
 * @extends {ol.format.XML}
+ * @todo stability experimental
 * @todo api
 */
 ol.format.WMSCapabilities = function() {
@@ -35,6 +36,7 @@ goog.inherits(ol.format.WMSCapabilities, ol.format.XML);
 * @function
 * @param {Document|Node|string} source The XML source.
 * @return {Object} An object representing the WMS capabilities.
+ * @todo stability experimental
 * @todo api
 */
 ol.format.WMSCapabilities.prototype.read;
--- a/src/ol/geolocation.js
+++ b/src/ol/geolocation.js
@@ -51,7 +51,6 @@ ol.GeolocationProperty = {
 * @constructor
 * @extends {ol.Object}
 * @param {olx.GeolocationOptions=} opt_options Options.
- * @todo stability experimental
 * @todo observable accuracy {number} readonly the accuracy of the position
 *       measurement in meters
 * @todo observable accuracyGeometry {ol.geom.Geometry} readonly a
@@ -72,6 +71,7 @@ ol.GeolocationProperty = {
 * @todo observable trackingOptions {GeolocationPositionOptions} PositionOptions
 *       as defined by the HTML5 Geolocation spec at
 *       http://www.w3.org/TR/geolocation-API/#position_options_interface
+ * @todo stability experimental
 * @todo api
 */
 ol.Geolocation = function(opt_options) {
--- a/src/ol/geom/geometry.js
+++ b/src/ol/geom/geometry.js
@@ -8,6 +8,7 @@ goog.require('ol.Observable');

 /**
 * @enum {string}
+ * @todo stability experimental
 */
 ol.geom.GeometryType = {
  POINT: 'Point',
@@ -24,6 +25,7 @@ ol.geom.GeometryType = {

 /**
 * @enum {string}
+ * @todo stability experimental
 */
 ol.geom.GeometryLayout = {
  XY: 'XY',
@@ -79,6 +81,7 @@ goog.inherits(ol.geom.Geometry, ol.Observable);


 /**
+ * @function
 * @return {ol.geom.Geometry} Clone.
 * @todo stability experimental
 */
@@ -113,7 +116,6 @@ ol.geom.Geometry.prototype.getClosestPoint = function(point, opt_closestPoint) {
 /**
 * @param {ol.Coordinate} coordinate Coordinate.
 * @return {boolean} Contains coordinate.
- * @todo stability experimental
 */
 ol.geom.Geometry.prototype.containsCoordinate = function(coordinate) {
  return this.containsXY(coordinate[0], coordinate[1]);
@@ -129,6 +131,7 @@ ol.geom.Geometry.prototype.containsXY = goog.functions.FALSE;


 /**
+ * @function
 * @param {ol.Extent=} opt_extent Extent.
 * @return {ol.Extent} extent Extent.
 * @todo stability experimental
@@ -137,21 +140,24 @@ ol.geom.Geometry.prototype.getExtent = goog.abstractMethod;


 /**
+ * @function
 * @param {number} squaredTolerance Squared tolerance.
 * @return {ol.geom.Geometry} Simplified geometry.
+ * @todo stability experimental
 */
 ol.geom.Geometry.prototype.getSimplifiedGeometry = goog.abstractMethod;


 /**
+ * @function
 * @return {ol.geom.GeometryType} Geometry type.
 * @todo stability experimental
- * @todo api
 */
 ol.geom.Geometry.prototype.getType = goog.abstractMethod;


 /**
+ * @function
 * @param {ol.TransformFunction} transformFn Transform.
 * @todo stability experimental
 */
--- a/src/ol/geom/geometrycollection.js
+++ b/src/ol/geom/geometrycollection.js
@@ -219,7 +219,6 @@ ol.geom.GeometryCollection.prototype.getType = function() {

 /**
 * @return {boolean} Is empty.
- * @todo stability experimental
 */
 ol.geom.GeometryCollection.prototype.isEmpty = function() {
  return goog.array.isEmpty(this.geometries_);
--- a/src/ol/geom/linestring.js
+++ b/src/ol/geom/linestring.js
@@ -60,6 +60,7 @@ goog.inherits(ol.geom.LineString, ol.geom.SimpleGeometry);

 /**
 * @param {ol.Coordinate} coordinate Coordinate.
+ * @todo stability experimental
 * @todo api
 */
 ol.geom.LineString.prototype.appendCoordinate = function(coordinate) {
@@ -116,6 +117,7 @@ ol.geom.LineString.prototype.closestPointXY =
 * @param {number} m M.
 * @param {boolean=} opt_extrapolate Extrapolate.
 * @return {ol.Coordinate} Coordinate.
+ * @todo stability experimental
 * @todo api
 */
 ol.geom.LineString.prototype.getCoordinateAtM = function(m, opt_extrapolate) {
--- a/src/ol/geom/multilinestring.js
+++ b/src/ol/geom/multilinestring.js
@@ -54,6 +54,7 @@ goog.inherits(ol.geom.MultiLineString, ol.geom.SimpleGeometry);

 /**
 * @param {ol.geom.LineString} lineString LineString.
+ * @todo stability experimental
 * @todo api
 */
 ol.geom.MultiLineString.prototype.appendLineString = function(lineString) {
@@ -121,6 +122,7 @@ ol.geom.MultiLineString.prototype.closestPointXY =
 * @param {boolean=} opt_extrapolate Extrapolate.
 * @param {boolean=} opt_interpolate Interpolate.
 * @return {ol.Coordinate} Coordinate.
+ * @todo stability experimental
 * @todo api
 */
 ol.geom.MultiLineString.prototype.getCoordinateAtM =
@@ -159,6 +161,7 @@ ol.geom.MultiLineString.prototype.getEnds = function() {
 /**
 * @param {number} index Index.
 * @return {ol.geom.LineString} LineString.
+ * @todo stability experimental
 * @todo api
 */
 ol.geom.MultiLineString.prototype.getLineString = function(index) {
@@ -289,7 +292,6 @@ ol.geom.MultiLineString.prototype.setFlatCoordinates =

 /**
 * @param {Array.<ol.geom.LineString>} lineStrings LineStrings.
- * @todo stability experimental
 */
 ol.geom.MultiLineString.prototype.setLineStrings = function(lineStrings) {
  var layout = ol.geom.GeometryLayout.XY;
--- a/src/ol/geom/multipoint.js
+++ b/src/ol/geom/multipoint.js
@@ -31,6 +31,7 @@ goog.inherits(ol.geom.MultiPoint, ol.geom.SimpleGeometry);

 /**
 * @param {ol.geom.Point} point Point.
+ * @todo stability experimental
 * @todo api
 */
 ol.geom.MultiPoint.prototype.appendPoint = function(point) {
@@ -96,6 +97,7 @@ ol.geom.MultiPoint.prototype.getCoordinates = function() {
 /**
 * @param {number} index Index.
 * @return {ol.geom.Point} Point.
+ * @todo stability experimental
 * @todo api
 */
 ol.geom.MultiPoint.prototype.getPoint = function(index) {
--- a/src/ol/geom/multipolygon.js
+++ b/src/ol/geom/multipolygon.js
@@ -83,6 +83,7 @@ goog.inherits(ol.geom.MultiPolygon, ol.geom.SimpleGeometry);

 /**
 * @param {ol.geom.Polygon} polygon Polygon.
+ * @todo stability experimental
 * @todo api
 */
 ol.geom.MultiPolygon.prototype.appendPolygon = function(polygon) {
@@ -196,6 +197,7 @@ ol.geom.MultiPolygon.prototype.getFlatInteriorPoints = function() {

 /**
 * @return {ol.geom.MultiPoint} Interior points.
+ * @todo stability experimental
 * @todo api
 */
 ol.geom.MultiPolygon.prototype.getInteriorPoints = function() {
@@ -248,6 +250,7 @@ ol.geom.MultiPolygon.prototype.getSimplifiedGeometryInternal =
 /**
 * @param {number} index Index.
 * @return {ol.geom.Polygon} Polygon.
+ * @todo stability experimental
 * @todo api
 */
 ol.geom.MultiPolygon.prototype.getPolygon = function(index) {
@@ -364,7 +367,6 @@ ol.geom.MultiPolygon.prototype.setFlatCoordinates =

 /**
 * @param {Array.<ol.geom.Polygon>} polygons Polygons.
- * @todo stability experimental
 */
 ol.geom.MultiPolygon.prototype.setPolygons = function(polygons) {
  var layout = ol.geom.GeometryLayout.XY;
--- a/src/ol/geom/polygon.js
+++ b/src/ol/geom/polygon.js
@@ -82,6 +82,7 @@ goog.inherits(ol.geom.Polygon, ol.geom.SimpleGeometry);

 /**
 * @param {ol.geom.LinearRing} linearRing Linear ring.
+ * @todo stability experimental
 * @todo api
 */
 ol.geom.Polygon.prototype.appendLinearRing = function(linearRing) {
@@ -184,6 +185,7 @@ ol.geom.Polygon.prototype.getFlatInteriorPoint = function() {

 /**
 * @return {ol.geom.Point} Interior point.
+ * @todo stability experimental
 * @todo api
 */
 ol.geom.Polygon.prototype.getInteriorPoint = function() {
@@ -194,6 +196,7 @@ ol.geom.Polygon.prototype.getInteriorPoint = function() {
 /**
 * @param {number} index Index.
 * @return {ol.geom.LinearRing} Linear ring.
+ * @todo stability experimental
 * @todo api
 */
 ol.geom.Polygon.prototype.getLinearRing = function(index) {
--- a/src/ol/geom/simplegeometry.js
+++ b/src/ol/geom/simplegeometry.js
@@ -103,6 +103,7 @@ ol.geom.SimpleGeometry.prototype.getExtent = function(opt_extent) {

 /**
 * @return {ol.Coordinate} First coordinate.
+ * @todo stability experimental
 * @todo api
 */
 ol.geom.SimpleGeometry.prototype.getFirstCoordinate = function() {
@@ -120,6 +121,7 @@ ol.geom.SimpleGeometry.prototype.getFlatCoordinates = function() {

 /**
 * @return {ol.Coordinate} Last point.
+ * @todo stability experimental
 * @todo api
 */
 ol.geom.SimpleGeometry.prototype.getLastCoordinate = function() {
--- a/src/ol/imagetile.js
+++ b/src/ol/imagetile.js
@@ -20,7 +20,6 @@ goog.require('ol.TileState');
 * @param {string} src Image source URI.
 * @param {?string} crossOrigin Cross origin.
 * @param {ol.TileLoadFunctionType} tileLoadFunction Tile load function.
- * @todo stability experimental
 */
 ol.ImageTile =
    function(tileCoord, state, src, crossOrigin, tileLoadFunction) {
--- a/src/ol/interaction/draganddropinteraction.js
+++ b/src/ol/interaction/draganddropinteraction.js
@@ -22,6 +22,7 @@ goog.require('ol.proj');
 * @fires {@link ol.interaction.DragAndDropEvent}
 *     ol.interaction.DragAndDropEvent
 * @param {olx.interaction.DragAndDropOptions=} opt_options Options.
+ * @todo stability experimental
 * @todo api
 */
 ol.interaction.DragAndDrop = function(opt_options) {
--- a/src/ol/interaction/dragboxinteraction.js
+++ b/src/ol/interaction/dragboxinteraction.js
@@ -136,6 +136,7 @@ ol.interaction.DragBox.prototype.handlePointerDrag = function(mapBrowserEvent) {
 /**
 * Returns geometry of last drawn box.
 * @return {ol.geom.Geometry} Geometry.
+ * @todo stability experimental
 * @todo api
 */
 ol.interaction.DragBox.prototype.getGeometry = function() {
--- a/src/ol/interaction/dragrotateinteraction.js
+++ b/src/ol/interaction/dragrotateinteraction.js
@@ -25,6 +25,7 @@ ol.interaction.DRAGROTATE_ANIMATION_DURATION = 250;
 * @constructor
 * @extends {ol.interaction.Pointer}
 * @param {olx.interaction.DragRotateOptions=} opt_options Options.
+ * @todo stability experimental
 * @todo api
 */
 ol.interaction.DragRotate = function(opt_options) {
--- a/src/ol/interaction/modifyinteraction.js
+++ b/src/ol/interaction/modifyinteraction.js
@@ -40,6 +40,7 @@ ol.interaction.SegmentDataType;
 * @constructor
 * @extends {ol.interaction.Pointer}
 * @param {olx.interaction.ModifyOptions} options Options.
+ * @todo stability experimental
 * @todo api
 */
 ol.interaction.Modify = function(options) {
--- a/src/ol/interaction/selectinteraction.js
+++ b/src/ol/interaction/selectinteraction.js
@@ -172,7 +172,9 @@ ol.interaction.Select.prototype.handleMapBrowserEvent =


 /**
- * @inheritDoc
+ * Remove the interaction from its current map, if any,  and attach it to a new
+ * map, if any. Pass `null` to just remove the interaction from the current map.
+ * @param {ol.Map} map Map.
 * @todo api
 */
 ol.interaction.Select.prototype.setMap = function(map) {
--- a/src/ol/iview.js
+++ b/src/ol/iview.js
@@ -8,6 +8,7 @@ goog.require('ol.IView3D');
 /**
 * Interface for views. Currently {@link ol.View2D} is implemented.
 * @interface
+ * @todo stability experimental
 */
 ol.IView = function() {
 };
--- a/src/ol/layer/layer.js
+++ b/src/ol/layer/layer.js
@@ -14,7 +14,6 @@ goog.require('ol.source.Source');
 * @extends {ol.layer.Base}
 * @fires {@link ol.render.Event} ol.render.Event
 * @param {olx.layer.LayerOptions} options Layer options.
- * @todo stability experimental
 * @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
@@ -23,6 +22,7 @@ goog.require('ol.source.Source');
 * @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 stability experimental
 * @todo api
 */
 ol.layer.Layer = function(options) {
--- a/src/ol/layer/layerbase.js
+++ b/src/ol/layer/layerbase.js
@@ -41,6 +41,8 @@ ol.layer.LayerState;


 /**
+ * Base class for all layers. The most basic implementation is
+ * {@link ol.layer.Layer}. See {@link ol.layer} for all implementations.
 * @constructor
 * @extends {ol.Object}
 * @param {olx.layer.BaseOptions} options Layer options.
@@ -77,6 +79,7 @@ goog.inherits(ol.layer.Base, ol.Object);

 /**
 * @return {number|undefined} Brightness.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.getBrightness = function() {
  return /** @type {number|undefined} */ (
@@ -90,6 +93,7 @@ goog.exportProperty(

 /**
 * @return {number|undefined} Contrast.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.getContrast = function() {
  return /** @type {number|undefined} */ (
@@ -103,6 +107,7 @@ goog.exportProperty(

 /**
 * @return {number|undefined} Hue.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.getHue = function() {
  return /** @type {number|undefined} */ (this.get(ol.layer.LayerProperty.HUE));
@@ -159,6 +164,7 @@ ol.layer.Base.prototype.getLayerStatesArray = goog.abstractMethod;

 /**
 * @return {number|undefined} MaxResolution.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.getMaxResolution = function() {
  return /** @type {number|undefined} */ (
@@ -172,6 +178,7 @@ goog.exportProperty(

 /**
 * @return {number|undefined} MinResolution.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.getMinResolution = function() {
  return /** @type {number|undefined} */ (
@@ -185,6 +192,7 @@ goog.exportProperty(

 /**
 * @return {number|undefined} Opacity.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.getOpacity = function() {
  return /** @type {number|undefined} */ (
@@ -198,6 +206,7 @@ goog.exportProperty(

 /**
 * @return {number|undefined} Saturation.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.getSaturation = function() {
  return /** @type {number|undefined} */ (
@@ -217,6 +226,7 @@ ol.layer.Base.prototype.getSourceState = goog.abstractMethod;

 /**
 * @return {boolean|undefined} Visible.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.getVisible = function() {
  return /** @type {boolean|undefined} */ (
@@ -247,6 +257,7 @@ goog.exportProperty(
 * [3] https://www.w3.org/Bugs/Public/show_bug.cgi?id=15647
 *
 * @param {number|undefined} brightness Brightness.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.setBrightness = function(brightness) {
  this.set(ol.layer.LayerProperty.BRIGHTNESS, brightness);
@@ -263,6 +274,7 @@ goog.exportProperty(
 * linear multipliers on the effect (and values over 1 are permitted).
 *
 * @param {number|undefined} contrast Contrast.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.setContrast = function(contrast) {
  this.set(ol.layer.LayerProperty.CONTRAST, contrast);
@@ -277,6 +289,7 @@ 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.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.setHue = function(hue) {
  this.set(ol.layer.LayerProperty.HUE, hue);
@@ -289,6 +302,7 @@ goog.exportProperty(

 /**
 * @param {number|undefined} maxResolution MaxResolution.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.setMaxResolution = function(maxResolution) {
  this.set(ol.layer.LayerProperty.MAX_RESOLUTION, maxResolution);
@@ -301,6 +315,7 @@ goog.exportProperty(

 /**
 * @param {number|undefined} minResolution MinResolution.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.setMinResolution = function(minResolution) {
  this.set(ol.layer.LayerProperty.MIN_RESOLUTION, minResolution);
@@ -313,6 +328,7 @@ goog.exportProperty(

 /**
 * @param {number|undefined} opacity Opacity.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.setOpacity = function(opacity) {
  this.set(ol.layer.LayerProperty.OPACITY, opacity);
@@ -330,6 +346,7 @@ goog.exportProperty(
 * permitted).
 *
 * @param {number|undefined} saturation Saturation.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.setSaturation = function(saturation) {
  this.set(ol.layer.LayerProperty.SATURATION, saturation);
@@ -342,6 +359,7 @@ goog.exportProperty(

 /**
 * @param {boolean|undefined} visible Visible.
+ * @todo stability experimental
 */
 ol.layer.Base.prototype.setVisible = function(visible) {
  this.set(ol.layer.LayerProperty.VISIBLE, visible);
--- a/src/ol/layer/layergroup.js
+++ b/src/ol/layer/layergroup.js
@@ -28,9 +28,9 @@ 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 stability experimental
- * @todo observable layers {ol.Collection} collection of layers that are part
- *       of this group
 * @todo api
 */
 ol.layer.Group = function(opt_options) {
--- a/src/ol/layer/tilelayer.js
+++ b/src/ol/layer/tilelayer.js
@@ -18,8 +18,8 @@ ol.layer.TileProperty = {
 * @extends {ol.layer.Layer}
 * @fires {@link ol.render.Event} ol.render.Event
 * @param {olx.layer.TileOptions} options Tile layer options.
- * @todo stability experimental
 * @todo observable preload {number} the level to preload tiles up to
+ * @todo stability experimental
 * @todo api
 */
 ol.layer.Tile = function(options) {
@@ -31,7 +31,6 @@ goog.inherits(ol.layer.Tile, ol.layer.Layer);

 /**
 * @return {number|undefined} Preload.
- * @todo stability experimental
 */
 ol.layer.Tile.prototype.getPreload = function() {
  return /** @type {number|undefined} */ (
@@ -45,7 +44,6 @@ goog.exportProperty(

 /**
 * @param {number} preload Preload.
- * @todo stability experimental
 */
 ol.layer.Tile.prototype.setPreload = function(preload) {
  this.set(ol.layer.TileProperty.PRELOAD, preload);
@@ -58,7 +56,6 @@ goog.exportProperty(

 /**
 * @return {boolean|undefined} Use interim tiles on error.
- * @todo stability experimental
 */
 ol.layer.Tile.prototype.getUseInterimTilesOnError = function() {
  return /** @type {boolean|undefined} */ (
@@ -72,7 +69,6 @@ goog.exportProperty(

 /**
 * @param {boolean|undefined} useInterimTilesOnError Use interim tiles on error.
- * @todo stability experimental
 */
 ol.layer.Tile.prototype.setUseInterimTilesOnError =
    function(useInterimTilesOnError) {
--- a/src/ol/layer/vectorlayer.js
+++ b/src/ol/layer/vectorlayer.js
@@ -71,6 +71,7 @@ ol.layer.Vector.prototype.getRenderOrder = function() {
 * option at construction or to the `setStyle` method.
 * @return {ol.style.Style|Array.<ol.style.Style>|ol.feature.StyleFunction}
 *     Layer style.
+ * @todo stability experimental
 * @todo api
 */
 ol.layer.Vector.prototype.getStyle = function() {
--- a/src/ol/loadingstrategy.js
+++ b/src/ol/loadingstrategy.js
@@ -7,6 +7,7 @@ goog.require('ol.TileCoord');
 * @param {ol.Extent} extent Extent.
 * @param {number} resolution Resolution.
 * @return {Array.<ol.Extent>} Extents.
+ * @todo stability experimental
 * @todo api
 */
 ol.loadingstrategy.all = function(extent, resolution) {
@@ -18,6 +19,7 @@ ol.loadingstrategy.all = function(extent, resolution) {
 * @param {ol.Extent} extent Extent.
 * @param {number} resolution Resolution.
 * @return {Array.<ol.Extent>} Extents.
+ * @todo stability experimental
 * @todo api
 */
 ol.loadingstrategy.bbox = function(extent, resolution) {
@@ -28,6 +30,7 @@ ol.loadingstrategy.bbox = function(extent, resolution) {
 /**
 * @param {ol.tilegrid.TileGrid} tileGrid Tile grid.
 * @return {function(ol.Extent, number): Array.<ol.Extent>} Loading strategy.
+ * @todo stability experimental
 * @todo api
 */
 ol.loadingstrategy.createTile = function(tileGrid) {
--- a/src/ol/map.js
+++ b/src/ol/map.js
@@ -158,13 +158,13 @@ ol.MapProperty = {
 * @fires {@link ol.MapBrowserEvent} ol.MapBrowserEvent
 * @fires {@link ol.MapEvent} ol.MapEvent
 * @fires {@link ol.render.Event} ol.render.Event
- * @todo stability experimental
- * @todo observable layergroup {ol.layer.LayerGroup} a layer group containing
- *       the layers in this map.
+ * @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
+ * @todo stability experimental
 * @todo api
 */
 ol.Map = function(options) {
--- a/src/ol/mapbrowserevent.js
+++ b/src/ol/mapbrowserevent.js
@@ -26,7 +26,6 @@ goog.require('ol.pointer.PointerEventHandler');
 * @param {ol.Map} map Map.
 * @param {goog.events.BrowserEvent} browserEvent Browser event.
 * @param {?oli.FrameState=} opt_frameState Frame state.
- * @todo stability experimental
 */
 ol.MapBrowserEvent = function(type, map, browserEvent, opt_frameState) {

@@ -95,7 +94,6 @@ ol.MapBrowserEvent.prototype.stopPropagation = function() {
 * @param {ol.Map} map Map.
 * @param {ol.pointer.PointerEvent} pointerEvent Pointer event.
 * @param {?oli.FrameState=} opt_frameState Frame state.
- * @todo stability experimental
 */
 ol.MapBrowserPointerEvent = function(type, map, pointerEvent, opt_frameState) {

--- a/src/ol/observable.js
+++ b/src/ol/observable.js
@@ -46,7 +46,6 @@ ol.Observable.prototype.dispatchChangeEvent = function() {

 /**
 * @return {number} Revision.
- * @todo stability experimental
 */
 ol.Observable.prototype.getRevision = function() {
  return this.revision_;
--- a/src/ol/overlay.js
+++ b/src/ol/overlay.js
@@ -56,13 +56,13 @@ ol.OverlayPositioning = {
 * @constructor
 * @extends {ol.Object}
 * @param {olx.OverlayOptions} options Overlay options.
- * @todo stability stable
 * @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 stability stable
 * @todo api
 */
 ol.Overlay = function(options) {
--- a/src/ol/proj/common.js
+++ b/src/ol/proj/common.js
@@ -7,6 +7,7 @@ goog.require('ol.proj.EPSG4326');

 /**
 * FIXME empty description for jsdoc
+ * @todo stability experimental
 * @todo api
 */
 ol.proj.common.add = function() {
--- a/src/ol/proj/proj.js
+++ b/src/ol/proj/proj.js
@@ -51,6 +51,7 @@ ol.proj.Units = {
 * Meters per unit lookup table.
 * @const
 * @type {Object.<ol.proj.Units, number>}
+ * @todo stability experimental
 * @todo api
 */
 ol.proj.METERS_PER_UNIT[ol.proj.Units.DEGREES] =
@@ -112,6 +113,7 @@ ol.proj.Projection = function(options) {
 /**
 * Get the code for this projection, e.g. 'EPSG:4326'.
 * @return {string} Code.
+ * @todo stability experimental
 * @todo api
 */
 ol.proj.Projection.prototype.getCode = function() {
@@ -122,6 +124,7 @@ ol.proj.Projection.prototype.getCode = function() {
 /**
 * Get the validity extent for this projection.
 * @return {ol.Extent} Extent.
+ * @todo stability experimental
 * @todo api
 */
 ol.proj.Projection.prototype.getExtent = function() {
@@ -145,6 +148,7 @@ ol.proj.Projection.prototype.getPointResolution = goog.abstractMethod;
 /**
 * Get the units of this projection.
 * @return {ol.proj.Units} Units.
+ * @todo stability experimental
 * @todo api
 */
 ol.proj.Projection.prototype.getUnits = function() {
--- a/src/ol/render/canvas/canvasimmediate.js
+++ b/src/ol/render/canvas/canvasimmediate.js
@@ -380,6 +380,7 @@ ol.render.canvas.Immediate.prototype.drawRings_ =
 *
 * @param {number} zIndex Z index.
 * @param {function(ol.render.canvas.Immediate)} callback Callback.
+ * @todo stability experimental
 * @todo api
 */
 ol.render.canvas.Immediate.prototype.drawAsync = function(zIndex, callback) {
@@ -477,7 +478,6 @@ ol.render.canvas.Immediate.prototype.drawFeature = function(feature, style) {
 * @param {ol.geom.GeometryCollection} geometryCollectionGeometry Geometry
 *     collection.
 * @param {Object} data Opaque data object.
- * @todo stability experimental
 */
 ol.render.canvas.Immediate.prototype.drawGeometryCollectionGeometry =
    function(geometryCollectionGeometry, data) {
--- a/src/ol/render/ivectorcontext.js
+++ b/src/ol/render/ivectorcontext.js
@@ -17,7 +17,6 @@ ol.render.IVectorContext = function() {
 /**
 * @param {number} zIndex Z index.
 * @param {function(ol.render.canvas.Immediate)} callback Callback.
- * @todo stability experimental
 */
 ol.render.IVectorContext.prototype.drawAsync = function(zIndex, callback) {
 };
@@ -26,7 +25,6 @@ ol.render.IVectorContext.prototype.drawAsync = function(zIndex, callback) {
 /**
 * @param {ol.geom.Circle} circleGeometry Circle geometry.
 * @param {Object} data Opaque data object,
- * @todo stability experimental
 */
 ol.render.IVectorContext.prototype.drawCircleGeometry =
    function(circleGeometry, data) {
@@ -36,7 +34,6 @@ ol.render.IVectorContext.prototype.drawCircleGeometry =
 /**
 * @param {ol.Feature} feature Feature.
 * @param {ol.style.Style} style Style.
- * @todo stability experimental
 */
 ol.render.IVectorContext.prototype.drawFeature = function(feature, style) {
 };
@@ -46,7 +43,6 @@ ol.render.IVectorContext.prototype.drawFeature = function(feature, style) {
 * @param {ol.geom.GeometryCollection} geometryCollectionGeometry Geometry
 *     collection.
 * @param {Object} data Opaque data object.
- * @todo stability experimental
 */
 ol.render.IVectorContext.prototype.drawGeometryCollectionGeometry =
    function(geometryCollectionGeometry, data) {
@@ -56,7 +52,6 @@ ol.render.IVectorContext.prototype.drawGeometryCollectionGeometry =
 /**
 * @param {ol.geom.Point} pointGeometry Point geometry.
 * @param {Object} data Opaque data object.
- * @todo stability experimental
 */
 ol.render.IVectorContext.prototype.drawPointGeometry =
    function(pointGeometry, data) {
@@ -66,7 +61,6 @@ ol.render.IVectorContext.prototype.drawPointGeometry =
 /**
 * @param {ol.geom.LineString} lineStringGeometry Line string geometry.
 * @param {Object} data Opaque data object.
- * @todo stability experimental
 */
 ol.render.IVectorContext.prototype.drawLineStringGeometry =
    function(lineStringGeometry, data) {
@@ -77,7 +71,6 @@ ol.render.IVectorContext.prototype.drawLineStringGeometry =
 * @param {ol.geom.MultiLineString} multiLineStringGeometry
 *     MultiLineString geometry.
 * @param {Object} data Opaque data object.
- * @todo stability experimental
 */
 ol.render.IVectorContext.prototype.drawMultiLineStringGeometry =
    function(multiLineStringGeometry, data) {
@@ -87,7 +80,6 @@ ol.render.IVectorContext.prototype.drawMultiLineStringGeometry =
 /**
 * @param {ol.geom.MultiPoint} multiPointGeometry MultiPoint geometry.
 * @param {Object} data Opaque data object.
- * @todo stability experimental
 */
 ol.render.IVectorContext.prototype.drawMultiPointGeometry =
    function(multiPointGeometry, data) {
@@ -97,7 +89,6 @@ ol.render.IVectorContext.prototype.drawMultiPointGeometry =
 /**
 * @param {ol.geom.MultiPolygon} multiPolygonGeometry MultiPolygon geometry.
 * @param {Object} data Opaque data object.
- * @todo stability experimental
 */
 ol.render.IVectorContext.prototype.drawMultiPolygonGeometry =
    function(multiPolygonGeometry, data) {
@@ -107,7 +98,6 @@ ol.render.IVectorContext.prototype.drawMultiPolygonGeometry =
 /**
 * @param {ol.geom.Polygon} polygonGeometry Polygon geometry.
 * @param {Object} data Opaque data object.
- * @todo stability experimental
 */
 ol.render.IVectorContext.prototype.drawPolygonGeometry =
    function(polygonGeometry, data) {
@@ -121,7 +111,6 @@ ol.render.IVectorContext.prototype.drawPolygonGeometry =
 * @param {number} stride Stride.
 * @param {ol.geom.Geometry} geometry Geometry.
 * @param {Object} data Opaque data object.
- * @todo stability experimental
 */
 ol.render.IVectorContext.prototype.drawText =
    function(flatCoordinates, offset, end, stride, geometry, data) {
@@ -131,7 +120,6 @@ ol.render.IVectorContext.prototype.drawText =
 /**
 * @param {ol.style.Fill} fillStyle Fill style.
 * @param {ol.style.Stroke} strokeStyle Stroke style.
- * @todo stability experimental
 */
 ol.render.IVectorContext.prototype.setFillStrokeStyle =
    function(fillStyle, strokeStyle) {
@@ -140,7 +128,6 @@ ol.render.IVectorContext.prototype.setFillStrokeStyle =

 /**
 * @param {ol.style.Image} imageStyle Image style.
- * @todo stability experimental
 */
 ol.render.IVectorContext.prototype.setImageStyle = function(imageStyle) {
 };
@@ -148,7 +135,6 @@ ol.render.IVectorContext.prototype.setImageStyle = function(imageStyle) {

 /**
 * @param {ol.style.Text} textStyle Text style.
- * @todo stability experimental
 */
 ol.render.IVectorContext.prototype.setTextStyle = function(textStyle) {
 };
--- a/src/ol/source/bingmapssource.js
+++ b/src/ol/source/bingmapssource.js
@@ -56,6 +56,7 @@ goog.inherits(ol.source.BingMaps, ol.source.TileImage);
 /**
 * @const
 * @type {ol.Attribution}
+ * @todo stability experimental
 * @todo api
 */
 ol.source.BingMaps.TOS_ATTRIBUTION = new ol.Attribution({
--- a/src/ol/source/formatvectorsource.js
+++ b/src/ol/source/formatvectorsource.js
@@ -23,7 +23,6 @@ goog.require('ol.xml');
 * @constructor
 * @extends {ol.source.Vector}
 * @param {olx.source.FormatVectorOptions} options Options.
- * @todo stability experimental
 */
 ol.source.FormatVector = function(options) {

--- a/src/ol/source/imagesource.js
+++ b/src/ol/source/imagesource.js
@@ -25,7 +25,6 @@ ol.source.ImageOptions;
 * @constructor
 * @extends {ol.source.Source}
 * @param {ol.source.ImageOptions} options Single image source options.
- * @todo stability experimental
 */
 ol.source.Image = function(options) {

--- a/src/ol/source/imagewmssource.js
+++ b/src/ol/source/imagewmssource.js
@@ -125,6 +125,7 @@ goog.inherits(ol.source.ImageWMS, ol.source.Image);
 *     in the `LAYERS` parameter will be used. `VERSION` should not be
 *     specified here.
 * @return {string|undefined} GetFeatureInfo URL.
+ * @todo stability experimental
 * @todo api
 */
 ol.source.ImageWMS.prototype.getGetFeatureInfoUrl =
@@ -175,6 +176,7 @@ ol.source.ImageWMS.prototype.getGetFeatureInfoUrl =
 * Get the user-provided params, i.e. those passed to the constructor through
 * the "params" option, and possibly updated using the updateParams method.
 * @return {Object} Params.
+ * @todo stability experimental
 * @todo api
 */
 ol.source.ImageWMS.prototype.getParams = function() {
@@ -328,6 +330,7 @@ ol.source.ImageWMS.prototype.getUrl = function() {

 /**
 * @param {string|undefined} url URL.
+ * @todo stability experimental
 * @todo api
 */
 ol.source.ImageWMS.prototype.setUrl = function(url) {
@@ -342,6 +345,7 @@ ol.source.ImageWMS.prototype.setUrl = function(url) {
 /**
 * Update the user-provided params.
 * @param {Object} params Params.
+ * @todo stability experimental
 * @todo api
 */
 ol.source.ImageWMS.prototype.updateParams = function(params) {
--- a/src/ol/source/mapguidesource.js
+++ b/src/ol/source/mapguidesource.js
@@ -13,6 +13,7 @@ goog.require('ol.source.Image');
 * @constructor
 * @extends {ol.source.Image}
 * @param {olx.source.MapGuideOptions} options Options.
+ * @todo stability experimental
 * @todo api
 */
 ol.source.MapGuide = function(options) {
--- a/src/ol/source/osmsource.js
+++ b/src/ol/source/osmsource.js
@@ -46,6 +46,7 @@ goog.inherits(ol.source.OSM, ol.source.XYZ);
 /**
 * @const
 * @type {ol.Attribution}
+ * @todo stability experimental
 * @todo api
 */
 ol.source.OSM.DATA_ATTRIBUTION = new ol.Attribution({
@@ -59,6 +60,7 @@ ol.source.OSM.DATA_ATTRIBUTION = new ol.Attribution({
 /**
 * @const
 * @type {ol.Attribution}
+ * @todo stability experimental
 * @todo api
 */
 ol.source.OSM.TILE_ATTRIBUTION = new ol.Attribution({
--- a/src/ol/source/osmxmlsource.js
+++ b/src/ol/source/osmxmlsource.js
@@ -10,6 +10,7 @@ goog.require('ol.source.StaticVector');
 * @extends {ol.source.StaticVector}
 * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
 * @param {olx.source.OSMXMLOptions=} opt_options Options.
+ * @todo stability experimental
 * @todo api
 */
 ol.source.OSMXML = function(opt_options) {
--- a/src/ol/source/servervectorsource.js
+++ b/src/ol/source/servervectorsource.js
@@ -13,6 +13,7 @@ goog.require('ol.structs.RBush');
 * @constructor
 * @extends {ol.source.FormatVector}
 * @param {olx.source.ServerVectorOptions} options Options.
+ * @todo stability experimental
 * @todo api
 */
 ol.source.ServerVector = function(options) {
@@ -104,6 +105,7 @@ ol.source.ServerVector.prototype.loadFeatures =
 * @function
 * @param {ArrayBuffer|Document|Node|Object|string} source Source.
 * @return {Array.<ol.Feature>} Features.
+ * @todo stability experimental
 * @todo api
 */
 ol.source.ServerVector.prototype.readFeatures;
--- a/src/ol/source/source.js
+++ b/src/ol/source/source.js
@@ -34,7 +34,6 @@ ol.source.SourceOptions;
 * @constructor
 * @extends {ol.Observable}
 * @param {ol.source.SourceOptions} options Source options.
- * @todo stability experimental
 */
 ol.source.Source = function(options) {

@@ -131,6 +130,7 @@ ol.source.Source.prototype.getResolutions = goog.abstractMethod;

 /**
 * @return {ol.source.State} State.
+ * @todo stability experimental
 * @todo api
 */
 ol.source.Source.prototype.getState = function() {
--- a/src/ol/source/tilesource.js
+++ b/src/ol/source/tilesource.js
@@ -154,6 +154,7 @@ ol.source.Tile.prototype.getTile = goog.abstractMethod;

 /**
 * @return {ol.tilegrid.TileGrid} Tile grid.
+ * @todo stability experimental
 * @todo api
 */
 ol.source.Tile.prototype.getTileGrid = function() {
--- a/src/ol/source/tilevectorsource.js
+++ b/src/ol/source/tilevectorsource.js
@@ -14,6 +14,7 @@ goog.require('ol.tilegrid.TileGrid');
 * @constructor
 * @extends {ol.source.FormatVector}
 * @param {olx.source.TileVectorOptions} options Options.
+ * @todo stability experimental
 * @todo api
 */
 ol.source.TileVector = function(options) {
@@ -230,7 +231,6 @@ ol.source.TileVector.prototype.setTileUrlFunction = function(tileUrlFunction) {

 /**
 * @param {string} url URL.
- * @todo stability experimental
 */
 ol.source.TileVector.prototype.setUrl = function(url) {
  this.setTileUrlFunction(ol.TileUrlFunction.createFromTemplates(
--- a/src/ol/source/tilewmssource.js
+++ b/src/ol/source/tilewmssource.js
@@ -125,6 +125,7 @@ goog.inherits(ol.source.TileWMS, ol.source.TileImage);
 *     in the `LAYERS` parameter will be used. `VERSION` should not be
 *     specified here.
 * @return {string|undefined} GetFeatureInfo URL.
+ * @todo stability experimental
 * @todo api
 */
 ol.source.TileWMS.prototype.getGetFeatureInfoUrl =
--- a/src/ol/source/vectorsource.js
+++ b/src/ol/source/vectorsource.js
@@ -149,7 +149,7 @@ ol.source.Vector.prototype.addFeaturesInternal = function(features) {


 /**
- * @todo stability experimental
+ * Clear the source
 */
 ol.source.Vector.prototype.clear = function() {
  this.rBush_.forEach(this.removeFeatureInternal, this);
@@ -181,7 +181,6 @@ ol.source.Vector.prototype.forEachFeature = function(f, opt_this) {
 * @param {T=} opt_this The object to use as `this` in `f`.
 * @return {S|undefined}
 * @template T,S
- * @todo stability experimental
 */
 ol.source.Vector.prototype.forEachFeatureAtCoordinate =
    function(coordinate, f, opt_this) {
@@ -220,7 +219,6 @@ ol.source.Vector.prototype.forEachFeatureInExtent =
 * @param {T=} opt_this The object to use as `this` in `f`.
 * @return {S|undefined}
 * @template T,S
- * @todo stability experimental
 */
 ol.source.Vector.prototype.forEachFeatureInExtentAtResolution =
    function(extent, resolution, f, opt_this) {
@@ -261,7 +259,6 @@ ol.source.Vector.prototype.getFeaturesAtCoordinate = function(coordinate) {
 /**
 * @param {ol.Extent} extent Extent.
 * @return {Array.<ol.Feature>} Features.
- * @todo stability experimental
 */
 ol.source.Vector.prototype.getFeaturesInExtent = function(extent) {
  return this.rBush_.getInExtent(extent);
@@ -354,7 +351,6 @@ ol.source.Vector.prototype.handleFeatureChange_ = function(event) {

 /**
 * @return {boolean} Is empty.
- * @todo stability experimental
 */
 ol.source.Vector.prototype.isEmpty = function() {
  return this.rBush_.isEmpty() &&
--- a/src/ol/structs/buffer.js
+++ b/src/ol/structs/buffer.js
@@ -29,7 +29,6 @@ ol.BUFFER_REPLACE_UNUSED_ENTRIES_WITH_NANS = goog.DEBUG;
 * @param {number=} opt_used Used.
 * @param {number=} opt_usage Usage.
 * @struct
- * @todo stability experimental
 */
 ol.structs.Buffer = function(opt_arr, opt_used, opt_usage) {

--- a/src/ol/style/circlestyle.js
+++ b/src/ol/style/circlestyle.js
@@ -92,6 +92,7 @@ ol.style.Circle.prototype.getAnchor = function() {

 /**
 * @return {ol.style.Fill} Fill style.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Circle.prototype.getFill = function() {
@@ -126,6 +127,7 @@ ol.style.Circle.prototype.getImageState = function() {

 /**
 * @return {number} Radius.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Circle.prototype.getRadius = function() {
@@ -144,6 +146,7 @@ ol.style.Circle.prototype.getSize = function() {

 /**
 * @return {ol.style.Stroke} Stroke style.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Circle.prototype.getStroke = function() {
--- a/src/ol/style/fillstyle.js
+++ b/src/ol/style/fillstyle.js
@@ -7,6 +7,7 @@ goog.require('ol.color');
 /**
 * @constructor
 * @param {olx.style.FillOptions=} opt_options Options.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Fill = function(opt_options) {
@@ -23,6 +24,7 @@ ol.style.Fill = function(opt_options) {

 /**
 * @return {ol.Color|string} Color.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Fill.prototype.getColor = function() {
--- a/src/ol/style/iconstyle.js
+++ b/src/ol/style/iconstyle.js
@@ -40,6 +40,7 @@ ol.style.IconAnchorUnits = {
 * @constructor
 * @param {olx.style.IconOptions=} opt_options Options.
 * @extends {ol.style.Image}
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Icon = function(opt_options) {
@@ -192,6 +193,7 @@ ol.style.Icon.prototype.getHitDetectionImage = function(pixelRatio) {

 /**
 * @return {string|undefined} Image src.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Icon.prototype.getSrc = function() {
--- a/src/ol/style/imagestyle.js
+++ b/src/ol/style/imagestyle.js
@@ -29,6 +29,7 @@ ol.style.ImageOptions;
 /**
 * @constructor
 * @param {ol.style.ImageOptions} options Options.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Image = function(options) {
@@ -84,6 +85,7 @@ ol.style.Image.prototype.getRotateWithView = function() {

 /**
 * @return {number} Rotation.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Image.prototype.getRotation = function() {
@@ -93,6 +95,7 @@ ol.style.Image.prototype.getRotation = function() {

 /**
 * @return {number} Scale.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Image.prototype.getScale = function() {
@@ -109,14 +112,18 @@ ol.style.Image.prototype.getSnapToPixel = function() {


 /**
+ * @function
 * @return {Array.<number>} Anchor.
+ * @todo stability experimental
 */
 ol.style.Image.prototype.getAnchor = goog.abstractMethod;


 /**
+ * @function
 * @param {number} pixelRatio Pixel ratio.
 * @return {HTMLCanvasElement|HTMLVideoElement|Image} Image element.
+ * @todo stability experimental
 */
 ol.style.Image.prototype.getImage = goog.abstractMethod;

@@ -135,7 +142,9 @@ ol.style.Image.prototype.getHitDetectionImage = goog.abstractMethod;


 /**
+ * @function
 * @return {ol.Size} Size.
+ * @todo stability experimental
 */
 ol.style.Image.prototype.getSize = goog.abstractMethod;

--- a/src/ol/style/strokestyle.js
+++ b/src/ol/style/strokestyle.js
@@ -7,6 +7,7 @@ goog.require('ol.color');
 /**
 * @constructor
 * @param {olx.style.StrokeOptions=} opt_options Options.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Stroke = function(opt_options) {
@@ -53,6 +54,7 @@ ol.style.Stroke = function(opt_options) {

 /**
 * @return {ol.Color|string} Color.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Stroke.prototype.getColor = function() {
@@ -62,6 +64,7 @@ ol.style.Stroke.prototype.getColor = function() {

 /**
 * @return {string|undefined} Line cap.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Stroke.prototype.getLineCap = function() {
@@ -71,6 +74,7 @@ ol.style.Stroke.prototype.getLineCap = function() {

 /**
 * @return {Array.<number>} Line dash.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Stroke.prototype.getLineDash = function() {
@@ -80,6 +84,7 @@ ol.style.Stroke.prototype.getLineDash = function() {

 /**
 * @return {string|undefined} Line join.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Stroke.prototype.getLineJoin = function() {
@@ -89,6 +94,7 @@ ol.style.Stroke.prototype.getLineJoin = function() {

 /**
 * @return {number|undefined} Miter limit.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Stroke.prototype.getMiterLimit = function() {
@@ -98,6 +104,7 @@ ol.style.Stroke.prototype.getMiterLimit = function() {

 /**
 * @return {number|undefined} Width.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Stroke.prototype.getWidth = function() {
--- a/src/ol/style/style.js
+++ b/src/ol/style/style.js
@@ -50,6 +50,7 @@ ol.style.Style = function(opt_options) {

 /**
 * @return {ol.style.Fill} Fill style.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Style.prototype.getFill = function() {
@@ -59,6 +60,7 @@ ol.style.Style.prototype.getFill = function() {

 /**
 * @return {ol.style.Image} Image style.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Style.prototype.getImage = function() {
@@ -68,6 +70,7 @@ ol.style.Style.prototype.getImage = function() {

 /**
 * @return {ol.style.Stroke} Stroke style.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Style.prototype.getStroke = function() {
@@ -77,6 +80,7 @@ ol.style.Style.prototype.getStroke = function() {

 /**
 * @return {ol.style.Text} Text style.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Style.prototype.getText = function() {
@@ -86,6 +90,7 @@ ol.style.Style.prototype.getText = function() {

 /**
 * @return {number|undefined} ZIndex.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Style.prototype.getZIndex = function() {
--- a/src/ol/style/textstyle.js
+++ b/src/ol/style/textstyle.js
@@ -5,6 +5,7 @@ goog.provide('ol.style.Text');
 /**
 * @constructor
 * @param {olx.style.TextOptions=} opt_options Options.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Text = function(opt_options) {
@@ -75,6 +76,7 @@ ol.style.Text = function(opt_options) {

 /**
 * @return {string|undefined} Font.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Text.prototype.getFont = function() {
@@ -100,6 +102,7 @@ ol.style.Text.prototype.getOffsetY = function() {

 /**
 * @return {ol.style.Fill} Fill style.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Text.prototype.getFill = function() {
@@ -109,6 +112,7 @@ ol.style.Text.prototype.getFill = function() {

 /**
 * @return {number|undefined} Rotation.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Text.prototype.getRotation = function() {
@@ -118,6 +122,7 @@ ol.style.Text.prototype.getRotation = function() {

 /**
 * @return {number|undefined} Scale.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Text.prototype.getScale = function() {
@@ -127,6 +132,7 @@ ol.style.Text.prototype.getScale = function() {

 /**
 * @return {ol.style.Stroke} Stroke style.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Text.prototype.getStroke = function() {
@@ -136,6 +142,7 @@ ol.style.Text.prototype.getStroke = function() {

 /**
 * @return {string|undefined} Text.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Text.prototype.getText = function() {
@@ -145,6 +152,7 @@ ol.style.Text.prototype.getText = function() {

 /**
 * @return {string|undefined} Text align.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Text.prototype.getTextAlign = function() {
@@ -154,6 +162,7 @@ ol.style.Text.prototype.getTextAlign = function() {

 /**
 * @return {string|undefined} Text baseline.
+ * @todo stability experimental
 * @todo api
 */
 ol.style.Text.prototype.getTextBaseline = function() {
--- a/src/ol/tilecoord.js
+++ b/src/ol/tilecoord.js
@@ -118,6 +118,7 @@ ol.TileCoord.getKeyZXY = function(z, x, y) {
 /**
 * @param {Array.<number>=} opt_result Optional array to reuse.
 * @return {Array.<number>} Array of z, x, y.
+ * @todo stability experimental
 * @todo api
 */
 ol.TileCoord.prototype.getZXY = function(opt_result) {
--- a/src/ol/tilegrid/tilegrid.js
+++ b/src/ol/tilegrid/tilegrid.js
@@ -140,7 +140,6 @@ ol.tilegrid.TileGrid.prototype.forEachTileCoordParentTileRange =

 /**
 * @return {number} Max zoom.
- * @todo stability experimental
 */
 ol.tilegrid.TileGrid.prototype.getMaxZoom = function() {
  return this.maxZoom;
@@ -177,6 +176,7 @@ ol.tilegrid.TileGrid.prototype.getOrigin = function(z) {
 /**
 * @param {number} z Z.
 * @return {number} Resolution.
+ * @todo stability experimental
 * @todo api
 */
 ol.tilegrid.TileGrid.prototype.getResolution = function(z) {
@@ -187,7 +187,6 @@ ol.tilegrid.TileGrid.prototype.getResolution = function(z) {

 /**
 * @return {Array.<number>} Resolutions.
- * @todo stability experimental
 */
 ol.tilegrid.TileGrid.prototype.getResolutions = function() {
  return this.resolutions_;
--- a/src/ol/webgl/context.js
+++ b/src/ol/webgl/context.js
@@ -23,6 +23,7 @@ ol.webgl.BufferCacheEntry;
 * @extends {goog.events.EventTarget}
 * @param {HTMLCanvasElement} canvas Canvas.
 * @param {WebGLRenderingContext} gl GL.
+ * @todo stability experimental
 * @todo api
 */
 ol.webgl.Context = function(canvas, gl) {
@@ -160,6 +161,7 @@ ol.webgl.Context.prototype.getCanvas = function() {

 /**
 * @return {WebGLRenderingContext} GL.
+ * @todo stability experimental
 * @todo api
 */
 ol.webgl.Context.prototype.getGL = function() {
@@ -248,6 +250,7 @@ ol.webgl.Context.prototype.handleWebGLContextRestored = function() {
 /**
 * @param {WebGLProgram} program Program.
 * @return {boolean} Changed.
+ * @todo stability experimental
 * @todo api
 */
 ol.webgl.Context.prototype.useProgram = function(program) {
--- a/src/oli.jsdoc
+++ b/src/oli.jsdoc
@@ -0,0 +1,3 @@
+/**
+ * @namespace oli
+ */