From 56a942e9cfea186d29e57ddfabca65e302a7fdc0 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 11:57:43 +0200 Subject: [PATCH 01/16] Stable map browser events --- src/ol/mapbrowserevent.js | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) 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', From d541ae49d04571288d4b5b32b3cc497fdb6bb129 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 12:03:21 +0200 Subject: [PATCH 02/16] Mark moveend as stable --- src/ol/mapevent.js | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) 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' + }; From 11ac778b29b896620f9adda582bfc234f77d782d Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 12:04:01 +0200 Subject: [PATCH 03/16] Mark propertychange as stable --- src/ol/object.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ol/object.js b/src/ol/object.js index a1723f8401..4b387322aa 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' }; From 89dc3a254b3b662cda99ddee3245ce2dab95413b Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 12:12:36 +0200 Subject: [PATCH 04/16] Stable object methods and events --- src/ol/object.js | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/src/ol/object.js b/src/ol/object.js index 4b387322aa..5dd3e0c369 100644 --- a/src/ol/object.js +++ b/src/ol/object.js @@ -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.} 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.} 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.} 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_) { From 21263f918462ff5319a97e9746bf1293f0a52f43 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 12:13:50 +0200 Subject: [PATCH 05/16] Stable view methods --- src/ol/view.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ol/view.js b/src/ol/view.js index 5fba81032a..fd5cb96b2b 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(), From 7ee8866f3564be8aa6059dc5cad7f20fba3f11d3 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 12:14:26 +0200 Subject: [PATCH 06/16] End the getResolutionForExtent experiment --- src/ol/view.js | 1 - 1 file changed, 1 deletion(-) diff --git a/src/ol/view.js b/src/ol/view.js index fd5cb96b2b..d47bb11b28 100644 --- a/src/ol/view.js +++ b/src/ol/view.js @@ -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]; From 0b2c09768656f18d3583b1d5dca10c523d7548a8 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 12:46:35 +0200 Subject: [PATCH 07/16] Stable format read/write options --- externs/olx.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/externs/olx.js b/externs/olx.js index 714db69548..819dc4127c 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; From 419483facedc464237b321e650f063c337e9fa13 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 12:56:11 +0200 Subject: [PATCH 08/16] Stable GeoJSON read/write methods --- src/ol/format/geojsonformat.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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.} 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) { From d79abe7448e6505ae3c38888992dcc30610c42b9 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 13:13:40 +0200 Subject: [PATCH 09/16] Stable geometry methods --- src/ol/geom/geometry.js | 7 ++++--- src/ol/geom/simplegeometry.js | 6 ++---- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/src/ol/geom/geometry.js b/src/ol/geom/geometry.js index 30ecaa7247..3583ccbb9f 100644 --- a/src/ol/geom/geometry.js +++ b/src/ol/geom/geometry.js @@ -202,17 +202,18 @@ ol.geom.Geometry.prototype.applyTransform = goog.abstractMethod; * @param {ol.Extent} extent Extent. * @return {boolean} `true` if the geometry and the extent intersect. * @function - * @api + * @api stable */ 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 + * @api stable */ ol.geom.Geometry.prototype.translate = goog.abstractMethod; 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(); From 5fe6f079697306e10309486ec8f0d1deea679a52 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 13:17:40 +0200 Subject: [PATCH 10/16] Make the source.getFeaturesInExtent() method exportable --- src/ol/source/vectorsource.js | 4 ++++ 1 file changed, 4 insertions(+) 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.} Features. + * @api */ ol.source.Vector.prototype.getFeaturesInExtent = function(extent) { return this.rBush_.getInExtent(extent); From cedc78972d2d2e362a556166b95a171dee625f31 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 13:19:18 +0200 Subject: [PATCH 11/16] Mark tile load events as stable --- src/ol/source/tilesource.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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' From 5c87efccdb326090b5660a1a4e1aabd8c61b7d43 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 13:51:45 +0200 Subject: [PATCH 12/16] Stable WMTS constructor and options --- externs/olx.js | 30 ++++++++++++++++-------------- src/ol/source/wmtssource.js | 2 +- 2 files changed, 17 insertions(+), 15 deletions(-) diff --git a/externs/olx.js b/externs/olx.js index 819dc4127c..4f18e4eef9 100644 --- a/externs/olx.js +++ b/externs/olx.js @@ -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.|undefined} - * @api + * @api stable */ olx.source.WMTSOptions.prototype.urls; 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) { From 6134a8bf7ae6858d6626d12f37d88e10430db8a8 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 14:40:21 +0200 Subject: [PATCH 13/16] Use @api annotations where geom methods are implemented --- src/ol/geom/geometry.js | 6 ------ 1 file changed, 6 deletions(-) diff --git a/src/ol/geom/geometry.js b/src/ol/geom/geometry.js index 3583ccbb9f..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,7 +199,6 @@ ol.geom.Geometry.prototype.applyTransform = goog.abstractMethod; * @param {ol.Extent} extent Extent. * @return {boolean} `true` if the geometry and the extent intersect. * @function - * @api stable */ ol.geom.Geometry.prototype.intersectsExtent = goog.abstractMethod; @@ -213,7 +209,6 @@ ol.geom.Geometry.prototype.intersectsExtent = goog.abstractMethod; * @param {number} deltaX Delta X. * @param {number} deltaY Delta Y. * @function - * @api stable */ ol.geom.Geometry.prototype.translate = goog.abstractMethod; @@ -231,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)); From 587c06f565605c3b311b6e62471354e27a0b9908 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 14:47:07 +0200 Subject: [PATCH 14/16] Stable intersectsExtent method for geometries --- src/ol/geom/geometrycollection.js | 2 +- src/ol/geom/linestring.js | 2 +- src/ol/geom/multilinestring.js | 2 +- src/ol/geom/multipoint.js | 2 +- src/ol/geom/multipolygon.js | 2 +- src/ol/geom/point.js | 2 +- src/ol/geom/polygon.js | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) 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( From 5bb7535207b18b5ad54ba83dede373f4053ecb51 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 14:48:51 +0200 Subject: [PATCH 15/16] Remove @api annotation from abstract method --- src/ol/style/imagestyle.js | 1 - 1 file changed, 1 deletion(-) 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; From 44ad7ce30a46b07c97512b9903ef049ce2b04413 Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Thu, 2 Apr 2015 14:51:59 +0200 Subject: [PATCH 16/16] Update doc on using @api annotation --- config/jsdoc/api/readme.md | 2 ++ 1 file changed, 2 insertions(+) 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: