Merge bb08234 into 65f18e3

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:

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,39 +5713,41 @@ olx.source.WMTSOptions.prototype.tilePixelRatio;
 /**
  * WMTS version. Default is `1.0.0`.
  * @type {string|undefined}
- * @api
+ * @api stable
  */
 olx.source.WMTSOptions.prototype.version;
 
 
 /**
  * Image format. Default is `image/jpeg`.
  * @type {string|undefined}
- * @api
+ * @api stable
  */
 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;
 

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) {

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));

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_;

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(

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(

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;

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(

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,

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(

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();

src/ol/mapbrowserevent.js

@@ -486,41 +486,44 @@ 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
    * @api
    */
   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',

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'
+
 };