Merge pull request #857 from elemoine/view2d-docs

Better View2D docs

src/objectliterals.jsdoc

@@ -88,21 +88,33 @@
 /**
  * Object literal with config options for the view.
  * @typedef {Object} ol.View2DOptions
- * @property {ol.Coordinate|undefined} center The view center in map projection.
- * @property {number|undefined} maxResolution The maximum resolution in map
- *     units per pixel.
- * @property {number|undefined} maxZoom The maximum zoom level for this view.
- *     Zoom level 0 uses the `maxResolution`; subsequent zoom levels are
- *     calculated by dividing the previous resolution by `zoomFactor`.
- * @property {ol.ProjectionLike} projection The map projection.
+ * @property {ol.Coordinate|undefined} center The initial center for the view.
+ *     The coordinate system for the center is specified with the `projection`
+ *     option.
+ * @property {number|undefined} maxResolution The maximum resolution used to
+ *     determine the resolution constraint. It is used together with `maxZoom`
+ *     and `zoomFactor`. If unspecified it is calculated in such a way that the
+ *     projection's validity extent fits in a 256x256 px tile. If the projection
+ *     is Spherical Mercator (the default) then `maxResolution` defaults to
+ *     40075016.68557849 / 256 = 156543.03392804097.
+ * @property {number|undefined} maxZoom The maximum zoom level used to determine
+ *     the resolution constraint. It is used together with `maxResolution` and
+ *     `zoomFactor`. Default is 28.
+ * @property {ol.ProjectionLike} projection The projection. Default is
+ *     `EPSG:3857` (Spherical Mercator).
  * @property {number|undefined} resolution The initial resolution for the view.
- * @property {Array.<number>|undefined} resolutions The resolutions for this
- *     view. If configured, this is equivalent to specifying `maxResolution` and
- *     `maxZoom`.
- * @property {number|undefined} rotation Initial rotation of the view.
- * @property {number|undefined} zoom Initial zoom level of the view.
- * @property {number|undefined} zoomFactor Factor to calculate resolutions for
- *     zoom levels. Default is 2.
+ *     The units are `projection` units per pixel (e.g. meters per pixel).
+ * @property {Array.<number>|undefined} resolutions Resolutions to determine the
+ *     resolution constraint. If set the `maxResolution`, `maxZoom` and
+ *     `zoomFactor` options are ignored.
+ * @property {number|undefined} rotation The initial rotation for the view
+ *     in radians (positive rotation clockwise).
+ * @property {number|undefined} zoom Zoom level used to calculate the initial
+ *     resolution for the view. The initial resolution is determined using the
+ *     `ol.View2D#constrainResolution` method.
+ * @property {number|undefined} zoomFactor The zoom factor used to determine the
+ *     resolution constraint. It is together with `maxResolution` and `maxZoom`.
+ *     Default is 2.
  */
 
 /**

src/ol/view2d.js

@@ -32,13 +32,51 @@ ol.View2DProperty = {
 
 
 /**
- * Create a new View2D, a View2D manages properties such as center,
- *     projection, resolution and rotation.
+ * @class
+ * An ol.View2D object represents a simple 2D view of the map.
  *
- * Example:
+ * This is the object to act upon to change the center, resolution,
+ * and rotation of the map.
  *
- *     // to get the current extent
- *     map.getView().getView2D().calculateExtent(map.getSize())
+ * ### The view states
+ *
+ * An `ol.View2D` is determined by three states: `center`, `resolution`,
+ * and `rotation`. To each state corresponds a getter and a setter. E.g.
+ * `getCenter` and `setCenter` for the `center` state.
+ *
+ * An `ol.View2D` has a `projection`. The projection determines the
+ * coordinate system of the center, and its units determine the units of the
+ * resolution (projection units per pixel). The default projection is
+ * Spherical Mercator (EPSG:3857).
+ *
+ * ### The constraints
+ *
+ * `setCenter`, `setResolution` and `setRotation` can be used to change the
+ * states of the view. Any value can be passed to the setters. And the value
+ * that is passed to a setter will effectively be the value set in the view,
+ * and returned by the corresponding getter.
+ *
+ * But an `ol.View2D` object also has a *resolution constraint* and a
+ * *rotation constraint*. There's currently no *center constraint*, but
+ * this may change in the future.
+ *
+ * As said above no constraints are applied when the setters are used to set
+ * new states for the view. Applying constraints is done explicitly through
+ * the use of the `constrain*` functions (`constrainResolution` and
+ * `constrainRotation`).
+ *
+ * The main users of the constraints are the interactions and the
+ * controls. For example, double-clicking on the map changes the view to
+ * the "next" resolution. And releasing the fingers after pinch-zooming
+ * snaps to the closest resolution (with an animation).
+ *
+ * So the *resolution constraint* snaps to specific resolutions. It is
+ * determined by the following options: `resolutions`, `maxResolution`,
+ * `maxZoom`, and `zoomFactor`. If `resolutions` is set, the other three
+ * options are ignored. See {@link ol.View2DOptions} for more information.
+ *
+ * The *rotation constaint* is currently not configurable. It snaps the
+ * rotation value to zero when approaching the horizontal.
  *
  * @constructor
  * @implements {ol.IView2D}