Merge pull request #2609 from elemoine/view-stability

Annotate stable view functions and options

externs/olx.js

@@ -457,7 +457,7 @@ olx.ViewOptions;
  * specified with the `projection` option. Default is `undefined`, and layer
  * sources will not be fetched if this is not set.
  * @type {ol.Coordinate|undefined}
- * @api
+ * @api stable
  */
 olx.ViewOptions.prototype.center;
 
@@ -498,7 +498,7 @@ olx.ViewOptions.prototype.extent;
  * (the default) then `maxResolution` defaults to `40075016.68557849 / 256 =
  * 156543.03392804097`.
  * @type {number|undefined}
- * @api
+ * @api stable
  */
 olx.ViewOptions.prototype.maxResolution;
 
@@ -511,7 +511,7 @@ olx.ViewOptions.prototype.maxResolution;
  * defaults to `40075016.68557849 / 256 / Math.pow(2, 28) =
  * 0.0005831682455839253`.
  * @type {number|undefined}
- * @api
+ * @api stable
  */
 olx.ViewOptions.prototype.minResolution;
 
@@ -522,7 +522,7 @@ olx.ViewOptions.prototype.minResolution;
  * is `28`.  Note that if `minResolution` is also provided, it is given
  * precedence over `maxZoom`.
  * @type {number|undefined}
- * @api
+ * @api stable
  */
 olx.ViewOptions.prototype.maxZoom;
 
@@ -533,7 +533,7 @@ olx.ViewOptions.prototype.maxZoom;
  * is `0`. Note that if `maxResolution` is also provided, it is given
  * precedence over `minZoom`.
  * @type {number|undefined}
- * @api
+ * @api stable
  */
 olx.ViewOptions.prototype.minZoom;
 
@@ -541,7 +541,7 @@ olx.ViewOptions.prototype.minZoom;
 /**
  * The projection. Default is `EPSG:3857` (Spherical Mercator).
  * @type {ol.proj.ProjectionLike}
- * @api
+ * @api stable
  */
 olx.ViewOptions.prototype.projection;
 
@@ -552,7 +552,7 @@ olx.ViewOptions.prototype.projection;
  * `zoom`. Default is `undefined`, and layer sources will not be fetched if
  * neither this nor `zoom` are defined.
  * @type {number|undefined}
- * @api
+ * @api stable
  */
 olx.ViewOptions.prototype.resolution;
 
@@ -562,7 +562,7 @@ olx.ViewOptions.prototype.resolution;
  * `maxResolution`, `minResolution`, `minZoom`, `maxZoom`, and `zoomFactor`
  * options are ignored.
  * @type {Array.<number>|undefined}
- * @api
+ * @api stable
  */
 olx.ViewOptions.prototype.resolutions;
 
@@ -571,7 +571,7 @@ olx.ViewOptions.prototype.resolutions;
  * The initial rotation for the view in radians (positive rotation clockwise).
  * Default is `0`.
  * @type {number|undefined}
- * @api
+ * @api stable
  */
 olx.ViewOptions.prototype.rotation;
 
@@ -581,7 +581,7 @@ olx.ViewOptions.prototype.rotation;
  * initial resolution for the view. The initial resolution is determined using
  * the `ol.View#constrainResolution` method.
  * @type {number|undefined}
- * @api
+ * @api stable
  */
 olx.ViewOptions.prototype.zoom;
 
@@ -589,7 +589,7 @@ olx.ViewOptions.prototype.zoom;
 /**
  * The zoom factor used to determine the resolution constraint.  Default is `2`.
  * @type {number|undefined}
- * @api
+ * @api stable
  */
 olx.ViewOptions.prototype.zoomFactor;
 

src/ol/view.js

@@ -89,7 +89,7 @@ ol.ViewHint = {
  * @constructor
  * @extends {ol.Object}
  * @param {olx.ViewOptions=} opt_options View options.
- * @api
+ * @api stable
  */
 ol.View = function(opt_options) {
   goog.base(this);
@@ -239,7 +239,7 @@ ol.View.prototype.constrainRotation = function(rotation, opt_delta) {
 /**
  * @return {ol.Coordinate|undefined} The center of the view.
  * @observable
- * @api
+ * @api stable
  */
 ol.View.prototype.getCenter = function() {
   return /** @type {ol.Coordinate|undefined} */ (
@@ -260,8 +260,10 @@ ol.View.prototype.getHints = function() {
 
 
 /**
- * Calculate the extent for the given size in pixels, based on the current
+ * Calculate the extent for the current view state and the passed `size`.
- * resolution and the current center.
+ * `size` is the size in pixels of the box into which the calculated extent
+ * should fit. In most cases you want to get the extent of the entire map,
+ * that is `map.getSize()`.
  * @param {ol.Size} size Box pixel size.
  * @return {ol.Extent} Extent.
  * @api
@@ -280,7 +282,7 @@ ol.View.prototype.calculateExtent = function(size) {
 
 /**
  * @return {ol.proj.Projection} The projection of the view.
- * @api
+ * @api stable
  */
 ol.View.prototype.getProjection = function() {
   return this.projection_;
@@ -290,7 +292,7 @@ ol.View.prototype.getProjection = function() {
 /**
  * @return {number|undefined} The resolution of the view.
  * @observable
- * @api
+ * @api stable
  */
 ol.View.prototype.getResolution = function() {
   return /** @type {number|undefined} */ (
@@ -345,7 +347,7 @@ ol.View.prototype.getResolutionForValueFunction = function(opt_power) {
 /**
  * @return {number|undefined} The rotation of the view.
  * @observable
- * @api
+ * @api stable
  */
 ol.View.prototype.getRotation = function() {
   return /** @type {number|undefined} */ (this.get(ol.ViewProperty.ROTATION));
@@ -403,7 +405,7 @@ ol.View.prototype.getState = function() {
  * Get the current zoom level. Return undefined if the current
  * resolution is undefined or not a "constrained resolution".
  * @return {number|undefined} Zoom.
- * @api
+ * @api stable
  */
 ol.View.prototype.getZoom = function() {
   var offset;
@@ -426,7 +428,9 @@ ol.View.prototype.getZoom = function() {
 
 
 /**
- * Fit the given extent based on the given map size.
+ * Fit the map view to the passed `extent` and `size`. `size` is the size in
+ * pixels of the box to fit the extent into. In most cases you will want to
+ * use the map size, that is `map.getSize()`.
  * @param {ol.Extent} extent Extent.
  * @param {ol.Size} size Box pixel size.
  * @api
@@ -560,7 +564,7 @@ ol.View.prototype.isDef = function() {
  * Rotate the view around a given coordinate.
  * @param {number} rotation New rotation value for the view.
  * @param {ol.Coordinate=} opt_anchor The rotation center.
- * @api
+ * @api stable
  */
 ol.View.prototype.rotate = function(rotation, opt_anchor) {
   if (goog.isDef(opt_anchor)) {
@@ -575,7 +579,7 @@ ol.View.prototype.rotate = function(rotation, opt_anchor) {
  * Set the center of the current view.
  * @param {ol.Coordinate|undefined} center The center of the view.
  * @observable
- * @api
+ * @api stable
  */
 ol.View.prototype.setCenter = function(center) {
   this.set(ol.ViewProperty.CENTER, center);
@@ -603,7 +607,7 @@ ol.View.prototype.setHint = function(hint, delta) {
  * Set the resolution for this view.
  * @param {number|undefined} resolution The resolution of the view.
  * @observable
- * @api
+ * @api stable
  */
 ol.View.prototype.setResolution = function(resolution) {
   this.set(ol.ViewProperty.RESOLUTION, resolution);
@@ -618,7 +622,7 @@ goog.exportProperty(
  * Set the rotation for this view.
  * @param {number|undefined} rotation The rotation of the view.
  * @observable
- * @api
+ * @api stable
  */
 ol.View.prototype.setRotation = function(rotation) {
   this.set(ol.ViewProperty.ROTATION, rotation);
@@ -632,7 +636,7 @@ goog.exportProperty(
 /**
  * Zoom to a specific zoom level.
  * @param {number} zoom Zoom level.
- * @api
+ * @api stable
  */
 ol.View.prototype.setZoom = function(zoom) {
   var resolution = this.constrainResolution(