diff --git a/config/jsdoc/api/readme.md b/config/jsdoc/api/readme.md
index 96bedc768b..a7e34c7763 100644
--- a/config/jsdoc/api/readme.md
+++ b/config/jsdoc/api/readme.md
@@ -24,6 +24,8 @@ The second line tells the Closure compiler the type of the argument.
 
 The third line (`@api`) marks the method as part of the api and thus exportable. The stability can be added as value, e.g. `@api stable`. Without such an api annotation, the method will not be documented in the generated API documentation. Symbols without an api annotation will also not be exportable (unless they are explicitly exported with a `goog.exportProperty` call).
 
+The `@api` annotation can be used in conjunciton with the `@inheritDoc` annotation to export a symbol that is documented on a parent class (where the method may be abstract).  In general, `@api` annotations should never be used on abstract methods (only on their implementations).
+
 ### Events
 
 Events are documented using `@fires` and `@event` annotations:
diff --git a/externs/olx.js b/externs/olx.js
index 714db69548..4f18e4eef9 100644
--- a/externs/olx.js
+++ b/externs/olx.js
@@ -1606,7 +1606,7 @@ olx.format.WriteOptions.prototype.featureProjection;
  * geometries.
  *
  * @type {boolean|undefined}
- * @api
+ * @api stable
  */
 olx.format.WriteOptions.prototype.rightHanded;
 
@@ -5668,23 +5668,23 @@ olx.source.WMTSOptions.prototype.projection;
 /**
  * Request encoding. Default is `KVP`.
  * @type {ol.source.WMTSRequestEncoding|string|undefined}
- * @api
+ * @api stable
  */
 olx.source.WMTSOptions.prototype.requestEncoding;
 
 
 /**
- * Layer.
+ * Layer name as advertised in the WMTS capabilities.
  * @type {string}
- * @api
+ * @api stable
  */
 olx.source.WMTSOptions.prototype.layer;
 
 
 /**
- * Style.
+ * Style name as advertised in the WMTS capabilities.
  * @type {string}
- * @api
+ * @api stable
  */
 olx.source.WMTSOptions.prototype.style;
 
@@ -5713,7 +5713,7 @@ olx.source.WMTSOptions.prototype.tilePixelRatio;
 /**
  * WMTS version. Default is `1.0.0`.
  * @type {string|undefined}
- * @api
+ * @api stable
  */
 olx.source.WMTSOptions.prototype.version;
 
@@ -5721,7 +5721,7 @@ olx.source.WMTSOptions.prototype.version;
 /**
  * Image format. Default is `image/jpeg`.
  * @type {string|undefined}
- * @api
+ * @api stable
  */
 olx.source.WMTSOptions.prototype.format;
 
@@ -5729,23 +5729,25 @@ olx.source.WMTSOptions.prototype.format;
 /**
  * Matrix set.
  * @type {string}
- * @api
+ * @api stable
  */
 olx.source.WMTSOptions.prototype.matrixSet;
 
 
 /**
- * Dimensions.
+ * Additional "dimensions" for tile requests.  This is an object with properties
+ * named like the advertised WMTS dimensions.
  * @type {Object|undefined}
- * @api
+ * @api stable
  */
 olx.source.WMTSOptions.prototype.dimensions;
 
 
 /**
- * URL.
+ * A URL for the service.  For the RESTful request encoding, this is a URL
+ * template.  For KVP encoding, it is normal URL.
  * @type {string|undefined}
- * @api
+ * @api stable
  */
 olx.source.WMTSOptions.prototype.url;
 
@@ -5767,9 +5769,9 @@ olx.source.WMTSOptions.prototype.tileLoadFunction;
 
 
 /**
- * Urls.
+ * An array of URLs.  Requests will be distributed among the URLs in this array.
  * @type {Array.<string>|undefined}
- * @api
+ * @api stable
  */
 olx.source.WMTSOptions.prototype.urls;
 
diff --git a/src/ol/format/geojsonformat.js b/src/ol/format/geojsonformat.js
index 4351d506ec..30dd616e59 100644
--- a/src/ol/format/geojsonformat.js
+++ b/src/ol/format/geojsonformat.js
@@ -524,8 +524,8 @@ ol.format.GeoJSON.prototype.writeFeature;
  *
  * @param {ol.Feature} feature Feature.
  * @param {olx.format.WriteOptions=} opt_options Write options.
- * @api
  * @return {Object} Object.
+ * @api stable
  */
 ol.format.GeoJSON.prototype.writeFeatureObject = function(
     feature, opt_options) {
@@ -571,7 +571,7 @@ ol.format.GeoJSON.prototype.writeFeatures;
  * @param {Array.<ol.Feature>} features Features.
  * @param {olx.format.WriteOptions=} opt_options Write options.
  * @return {Object} GeoJSON Object.
- * @api
+ * @api stable
  */
 ol.format.GeoJSON.prototype.writeFeaturesObject =
     function(features, opt_options) {
@@ -606,7 +606,7 @@ ol.format.GeoJSON.prototype.writeGeometry;
  * @param {ol.geom.Geometry} geometry Geometry.
  * @param {olx.format.WriteOptions=} opt_options Write options.
  * @return {GeoJSONGeometry|GeoJSONGeometryCollection} Object.
- * @api
+ * @api stable
  */
 ol.format.GeoJSON.prototype.writeGeometryObject = function(geometry,
     opt_options) {
diff --git a/src/ol/geom/geometry.js b/src/ol/geom/geometry.js
index 30ecaa7247..24f22bac86 100644
--- a/src/ol/geom/geometry.js
+++ b/src/ol/geom/geometry.js
@@ -96,7 +96,6 @@ goog.inherits(ol.geom.Geometry, ol.Object);
  * Make a complete copy of the geometry.
  * @function
  * @return {!ol.geom.Geometry} Clone.
- * @api stable
  */
 ol.geom.Geometry.prototype.clone = goog.abstractMethod;
 
@@ -180,7 +179,6 @@ ol.geom.Geometry.prototype.getSimplifiedGeometry = goog.abstractMethod;
  * Get the type of this geometry.
  * @function
  * @return {ol.geom.GeometryType} Geometry type.
- * @api stable
  */
 ol.geom.Geometry.prototype.getType = goog.abstractMethod;
 
@@ -192,7 +190,6 @@ ol.geom.Geometry.prototype.getType = goog.abstractMethod;
  * then use this function on the clone.
  * @function
  * @param {ol.TransformFunction} transformFn Transform.
- * @api stable
  */
 ol.geom.Geometry.prototype.applyTransform = goog.abstractMethod;
 
@@ -202,17 +199,16 @@ ol.geom.Geometry.prototype.applyTransform = goog.abstractMethod;
  * @param {ol.Extent} extent Extent.
  * @return {boolean} `true` if the geometry and the extent intersect.
  * @function
- * @api
  */
 ol.geom.Geometry.prototype.intersectsExtent = goog.abstractMethod;
 
 
 /**
- * Translate the geometry.
+ * Translate the geometry.  This modifies the geometry coordinates in place.  If
+ * instead you want a new geometry, first `clone()` this geometry.
  * @param {number} deltaX Delta X.
  * @param {number} deltaY Delta Y.
  * @function
- * @api
  */
 ol.geom.Geometry.prototype.translate = goog.abstractMethod;
 
@@ -230,7 +226,6 @@ ol.geom.Geometry.prototype.translate = goog.abstractMethod;
  *     string identifier or a {@link ol.proj.Projection} object.
  * @return {ol.geom.Geometry} This geometry.  Note that original geometry is
  *     modified in place.
- * @api stable
  */
 ol.geom.Geometry.prototype.transform = function(source, destination) {
   this.applyTransform(ol.proj.getTransform(source, destination));
diff --git a/src/ol/geom/geometrycollection.js b/src/ol/geom/geometrycollection.js
index 6cbe1c2559..ee9d41d6cd 100644
--- a/src/ol/geom/geometrycollection.js
+++ b/src/ol/geom/geometrycollection.js
@@ -212,7 +212,7 @@ ol.geom.GeometryCollection.prototype.getType = function() {
 
 /**
  * @inheritDoc
- * @api
+ * @api stable
  */
 ol.geom.GeometryCollection.prototype.intersectsExtent = function(extent) {
   var geometries = this.geometries_;
diff --git a/src/ol/geom/linestring.js b/src/ol/geom/linestring.js
index 36829afa71..0039f8e88d 100644
--- a/src/ol/geom/linestring.js
+++ b/src/ol/geom/linestring.js
@@ -214,7 +214,7 @@ ol.geom.LineString.prototype.getType = function() {
 
 /**
  * @inheritDoc
- * @api
+ * @api stable
  */
 ol.geom.LineString.prototype.intersectsExtent = function(extent) {
   return ol.geom.flat.intersectsextent.lineString(
diff --git a/src/ol/geom/multilinestring.js b/src/ol/geom/multilinestring.js
index e33c1421fb..41b5977953 100644
--- a/src/ol/geom/multilinestring.js
+++ b/src/ol/geom/multilinestring.js
@@ -249,7 +249,7 @@ ol.geom.MultiLineString.prototype.getType = function() {
 
 /**
  * @inheritDoc
- * @api
+ * @api stable
  */
 ol.geom.MultiLineString.prototype.intersectsExtent = function(extent) {
   return ol.geom.flat.intersectsextent.lineStrings(
diff --git a/src/ol/geom/multipoint.js b/src/ol/geom/multipoint.js
index 8ff772c059..8005413761 100644
--- a/src/ol/geom/multipoint.js
+++ b/src/ol/geom/multipoint.js
@@ -146,7 +146,7 @@ ol.geom.MultiPoint.prototype.getType = function() {
 
 /**
  * @inheritDoc
- * @api
+ * @api stable
  */
 ol.geom.MultiPoint.prototype.intersectsExtent = function(extent) {
   var flatCoordinates = this.flatCoordinates;
diff --git a/src/ol/geom/multipolygon.js b/src/ol/geom/multipolygon.js
index 9372670748..c5212ea13a 100644
--- a/src/ol/geom/multipolygon.js
+++ b/src/ol/geom/multipolygon.js
@@ -338,7 +338,7 @@ ol.geom.MultiPolygon.prototype.getType = function() {
 
 /**
  * @inheritDoc
- * @api
+ * @api stable
  */
 ol.geom.MultiPolygon.prototype.intersectsExtent = function(extent) {
   return ol.geom.flat.intersectsextent.linearRingss(
diff --git a/src/ol/geom/point.js b/src/ol/geom/point.js
index cbd895ab19..bb69afa415 100644
--- a/src/ol/geom/point.js
+++ b/src/ol/geom/point.js
@@ -88,7 +88,7 @@ ol.geom.Point.prototype.getType = function() {
 
 /**
  * @inheritDoc
- * @api
+ * @api stable
  */
 ol.geom.Point.prototype.intersectsExtent = function(extent) {
   return ol.extent.containsXY(extent,
diff --git a/src/ol/geom/polygon.js b/src/ol/geom/polygon.js
index 8771a8793f..55fdff36f5 100644
--- a/src/ol/geom/polygon.js
+++ b/src/ol/geom/polygon.js
@@ -318,7 +318,7 @@ ol.geom.Polygon.prototype.getType = function() {
 
 /**
  * @inheritDoc
- * @api
+ * @api stable
  */
 ol.geom.Polygon.prototype.intersectsExtent = function(extent) {
   return ol.geom.flat.intersectsextent.linearRings(
diff --git a/src/ol/geom/simplegeometry.js b/src/ol/geom/simplegeometry.js
index 456dc28755..d943f00d95 100644
--- a/src/ol/geom/simplegeometry.js
+++ b/src/ol/geom/simplegeometry.js
@@ -249,10 +249,8 @@ ol.geom.SimpleGeometry.prototype.applyTransform = function(transformFn) {
 
 
 /**
- * Translate the geometry.
- * @param {number} deltaX Delta X.
- * @param {number} deltaY Delta Y.
- * @api
+ * @inheritDoc
+ * @api stable
  */
 ol.geom.SimpleGeometry.prototype.translate = function(deltaX, deltaY) {
   var flatCoordinates = this.getFlatCoordinates();
diff --git a/src/ol/mapbrowserevent.js b/src/ol/mapbrowserevent.js
index 9fb76bb6a5..b3cd8a3584 100644
--- a/src/ol/mapbrowserevent.js
+++ b/src/ol/mapbrowserevent.js
@@ -486,26 +486,29 @@ ol.MapBrowserEventHandler.prototype.disposeInternal = function() {
  * @enum {string}
  */
 ol.MapBrowserEvent.EventType = {
-  // derived event types
+
   /**
    * 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
-   * @api
+   * @api stable
    */
   SINGLECLICK: 'singleclick',
+
   /**
    * A click with no dragging. A double click will fire two of this.
    * @event ol.MapBrowserEvent#click
-   * @api
+   * @api stable
    */
   CLICK: goog.events.EventType.CLICK,
+
   /**
    * A true double click, with no dragging.
    * @event ol.MapBrowserEvent#dblclick
-   * @api
+   * @api stable
    */
   DBLCLICK: goog.events.EventType.DBLCLICK,
+
   /**
    * Triggered when a pointer is dragged.
    * @event ol.MapBrowserEvent#pointerdrag
@@ -513,14 +516,14 @@ ol.MapBrowserEvent.EventType = {
    */
   POINTERDRAG: 'pointerdrag',
 
-  // original pointer event types
   /**
    * Triggered when a pointer is moved. Note that on touch devices this is
    * triggered when the map is panned, so is not the same as mousemove.
    * @event ol.MapBrowserEvent#pointermove
-   * @api
+   * @api stable
    */
   POINTERMOVE: 'pointermove',
+
   POINTERDOWN: 'pointerdown',
   POINTERUP: 'pointerup',
   POINTEROVER: 'pointerover',
diff --git a/src/ol/mapevent.js b/src/ol/mapevent.js
index 260d002ac5..909a774f23 100644
--- a/src/ol/mapevent.js
+++ b/src/ol/mapevent.js
@@ -8,18 +8,21 @@ goog.require('goog.events.Event');
  * @enum {string}
  */
 ol.MapEventType = {
+
   /**
    * Triggered after a map frame is rendered.
    * @event ol.MapEvent#postrender
    * @api
    */
   POSTRENDER: 'postrender',
+
   /**
    * Triggered after the map is moved.
    * @event ol.MapEvent#moveend
-   * @api
+   * @api stable
    */
   MOVEEND: 'moveend'
+
 };
 
 
diff --git a/src/ol/object.js b/src/ol/object.js
index a1723f8401..5dd3e0c369 100644
--- a/src/ol/object.js
+++ b/src/ol/object.js
@@ -23,7 +23,7 @@ ol.ObjectEventType = {
   /**
    * Triggered when a property is changed.
    * @event ol.ObjectEvent#propertychange
-   * @api
+   * @api stable
    */
   PROPERTYCHANGE: 'propertychange'
 };
@@ -47,7 +47,7 @@ ol.ObjectEvent = function(type, key, oldValue) {
   /**
    * The name of the property whose value is changing.
    * @type {string}
-   * @api
+   * @api stable
    */
   this.key = key;
 
@@ -55,7 +55,7 @@ ol.ObjectEvent = function(type, key, oldValue) {
    * The old value. To get the new value use `e.target.get(e.key)` where
    * `e` is the event object.
    * @type {*}
-   * @api
+   * @api stable
    */
   this.oldValue = oldValue;
 
@@ -352,7 +352,7 @@ ol.Object.prototype.bindTo = function(key, target, opt_targetKey) {
  * Gets a value.
  * @param {string} key Key name.
  * @return {*} Value.
- * @api
+ * @api stable
  */
 ol.Object.prototype.get = function(key) {
   var value;
@@ -371,7 +371,7 @@ ol.Object.prototype.get = function(key) {
 /**
  * Get a list of object property names.
  * @return {Array.<string>} List of property names.
- * @api
+ * @api stable
  */
 ol.Object.prototype.getKeys = function() {
   var accessors = this.accessors_;
@@ -403,7 +403,7 @@ ol.Object.prototype.getKeys = function() {
 /**
  * Get an object of all property names and values.
  * @return {Object.<string, *>} Object.
- * @api
+ * @api stable
  */
 ol.Object.prototype.getProperties = function() {
   var properties = {};
@@ -435,7 +435,7 @@ ol.Object.prototype.notify = function(key, oldValue) {
  * Sets a value.
  * @param {string} key Key name.
  * @param {*} value Value.
- * @api
+ * @api stable
  */
 ol.Object.prototype.set = function(key, value) {
   var accessors = this.accessors_;
@@ -452,9 +452,10 @@ ol.Object.prototype.set = function(key, value) {
 
 
 /**
- * Sets a collection of key-value pairs.
+ * Sets a collection of key-value pairs.  Note that this changes any existing
+ * properties and adds new ones (it does not remove any existing properties).
  * @param {Object.<string, *>} values Values.
- * @api
+ * @api stable
  */
 ol.Object.prototype.setProperties = function(values) {
   var key;
@@ -497,7 +498,7 @@ ol.Object.prototype.unbindAll = function() {
 /**
  * Unsets a property.
  * @param {string} key Key name.
- * @api
+ * @api stable
  */
 ol.Object.prototype.unset = function(key) {
   if (key in this.values_) {
diff --git a/src/ol/source/tilesource.js b/src/ol/source/tilesource.js
index 58acb045e4..4e8d0988c8 100644
--- a/src/ol/source/tilesource.js
+++ b/src/ol/source/tilesource.js
@@ -280,21 +280,21 @@ ol.source.TileEventType = {
   /**
    * Triggered when a tile starts loading.
    * @event ol.source.TileEvent#tileloadstart
-   * @api
+   * @api stable
    */
   TILELOADSTART: 'tileloadstart',
 
   /**
    * Triggered when a tile finishes loading.
    * @event ol.source.TileEvent#tileloadend
-   * @api
+   * @api stable
    */
   TILELOADEND: 'tileloadend',
 
   /**
    * Triggered if tile loading results in an error.
    * @event ol.source.TileEvent#tileloaderror
-   * @api
+   * @api stable
    */
   TILELOADERROR: 'tileloaderror'
 
diff --git a/src/ol/source/vectorsource.js b/src/ol/source/vectorsource.js
index 352c111b41..53446596bf 100644
--- a/src/ol/source/vectorsource.js
+++ b/src/ol/source/vectorsource.js
@@ -423,8 +423,12 @@ ol.source.Vector.prototype.getFeaturesAtCoordinate = function(coordinate) {
 
 
 /**
+ * Get all features in the provided extent.  Note that this returns all features
+ * whose bounding boxes intersect the given extent (so it may include features
+ * whose geometries do not intersect the extent).
  * @param {ol.Extent} extent Extent.
  * @return {Array.<ol.Feature>} Features.
+ * @api
  */
 ol.source.Vector.prototype.getFeaturesInExtent = function(extent) {
   return this.rBush_.getInExtent(extent);
diff --git a/src/ol/source/wmtssource.js b/src/ol/source/wmtssource.js
index f1bd00fc02..0028ee6100 100644
--- a/src/ol/source/wmtssource.js
+++ b/src/ol/source/wmtssource.js
@@ -34,7 +34,7 @@ ol.source.WMTSRequestEncoding = {
  * @constructor
  * @extends {ol.source.TileImage}
  * @param {olx.source.WMTSOptions} options WMTS options.
- * @api
+ * @api stable
  */
 ol.source.WMTS = function(options) {
 
diff --git a/src/ol/style/imagestyle.js b/src/ol/style/imagestyle.js
index 1cb95b241e..1989843a12 100644
--- a/src/ol/style/imagestyle.js
+++ b/src/ol/style/imagestyle.js
@@ -124,7 +124,6 @@ ol.style.Image.prototype.getAnchor = goog.abstractMethod;
  * @function
  * @param {number} pixelRatio Pixel ratio.
  * @return {HTMLCanvasElement|HTMLVideoElement|Image} Image element.
- * @api
  */
 ol.style.Image.prototype.getImage = goog.abstractMethod;
 
diff --git a/src/ol/view.js b/src/ol/view.js
index 5fba81032a..d47bb11b28 100644
--- a/src/ol/view.js
+++ b/src/ol/view.js
@@ -272,7 +272,7 @@ ol.View.prototype.getHints = function() {
  * that is `map.getSize()`.
  * @param {ol.Size} size Box pixel size.
  * @return {ol.Extent} Extent.
- * @api
+ * @api stable
  */
 ol.View.prototype.calculateExtent = function(size) {
   goog.asserts.assert(this.isDef(),
@@ -317,7 +317,6 @@ goog.exportProperty(
  * @param {ol.Size} size Box pixel size.
  * @return {number} The resolution at which the provided extent will render at
  *     the given size.
- * @api
  */
 ol.View.prototype.getResolutionForExtent = function(extent, size) {
   var xResolution = ol.extent.getWidth(extent) / size[0];