Merge pull request #3464 from tschaub/stable

Mark more of the API stable.
2015-04-02 16:44:06 +02:00
parent 65f18e3caf 44ad7ce30a
commit de9ad900c8
20 changed files with 66 additions and 60 deletions
--- 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:
--- 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;

--- 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) {
--- 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));
--- 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_;
--- 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(
--- 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(
--- 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;
--- 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(
--- 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,
--- 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(
--- 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();
--- 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',
--- 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'
+
 };


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

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

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

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