Merge pull request openlayers#2207 from probins/projdocs

Improve docs for projection/transform functions

apidoc/index.md

@@ -30,7 +30,7 @@ Interactions for [vector features](ol.Feature.html)
 <br>[Formats](ol.format.Feature.html) for reading/writing vector data
 <br>[ol.format.WMSCapabilities](ol.format.WMSCapabilities.html)</td></tr>
 <tr><th>Projections</th><th>2-way bindings</th><th>Other components</th></tr>
-<tr><td><p>All coordinates and extents need to be provided in map projection (default: [EPSG:3857](ol.proj.EPSG3857.html)). To transform, use [ol.proj.transform()](ol.proj.html#transform).</p>
+<tr><td><p>All coordinates and extents need to be provided in view projection (default: [EPSG:3857](ol.proj.EPSG3857.html)). To transform, use [ol.proj.transform()](ol.proj.html#transform) and [ol.extent.applyTransform()](ol.extent.html#applyTransform).</p>
 [ol.proj](ol.proj.html)</td>
 <td><p>[Objects](ol.Object.html) can be kept in sync using the [bindTo()](ol.Object.html#bindTo) method.</p>
 <p>A [DOM Input](ol.dom.Input.html) class is available to bind Object properties to HTML Input elements.</p></td>

src/ol/geom/geometry.js

@@ -167,6 +167,8 @@ ol.geom.Geometry.prototype.getType = goog.abstractMethod;
 
 /**
  * Apply a transform function to the geometry.  Modifies the geometry in place.
+ * If you do not want the geometry modified in place, first clone() it and
+ * then use this function on the clone.
  * @function
  * @param {ol.TransformFunction} transformFn Transform.
  * @todo api
@@ -177,6 +179,8 @@ ol.geom.Geometry.prototype.applyTransform = goog.abstractMethod;
 /**
  * Transform a geometry from one coordinate reference system to another.
  * Modifies the geometry in place.
+ * If you do not want the geometry modified in place, first clone() it and
+ * then use this function on the clone.
  *
  * @param {ol.proj.ProjectionLike} source The current projection.  Can be a
  *     string identifier or a {@link ol.proj.Projection} object.

src/ol/proj/epsg4326projection.js

@@ -10,6 +10,10 @@ goog.require('ol.proj.Units');
  * @classdesc
  * Projection object for WGS84 geographic coordinates (EPSG:4326).
  *
+ * Note that OpenLayers does not strictly comply with the EPSG definition.
+ * The EPSG registry defines 4326 as a CRS for Latitude,Longitude (y,x).
+ * OpenLayers treats EPSG:4326 as a pseudo-projection, with x,y coordinates.
+ *
  * @constructor
  * @extends {ol.proj.Projection}
  * @param {string} code Code.

src/ol/proj/proj.js

@@ -381,7 +381,9 @@ ol.proj.addProj4jsProjection_ = function(proj4jsProjection) {
 
 
 /**
- * @param {ol.proj.Projection} projection Projection.
+ * Add a Projection object to the list of supported projections.
+ *
+ * @param {ol.proj.Projection} projection Projection object.
  * @todo api
  */
 ol.proj.addProjection = function(projection) {
@@ -476,10 +478,12 @@ ol.proj.removeTransform = function(source, destination) {
 
 
 /**
+ * Fetches a Projection object for the code specified.
+ *
  * @param {ol.proj.ProjectionLike} projectionLike Either a code string which is
  *     a combination of authority and identifier such as "EPSG:4326", or an
  *     existing projection object, or undefined.
- * @return {ol.proj.Projection} Projection.
+ * @return {ol.proj.Projection} Projection object, or null if not in list.
  * @todo api
  */
 ol.proj.get = function(projectionLike) {
@@ -555,13 +559,13 @@ ol.proj.equivalent = function(projection1, projection2) {
 
 
 /**
- * Given the projection-like objects this method searches for a transformation
+ * Given the projection-like objects, searches for a transformation
  * function to convert a coordinates array from the source projection to the
  * destination projection.
  *
  * @param {ol.proj.ProjectionLike} source Source.
  * @param {ol.proj.ProjectionLike} destination Destination.
- * @return {ol.TransformFunction} Transform.
+ * @return {ol.TransformFunction} Transform function.
  * @todo api
  */
 ol.proj.getTransform = function(source, destination) {
@@ -573,12 +577,13 @@ ol.proj.getTransform = function(source, destination) {
 
 
 /**
- * Searches a function that can be used to convert coordinates from the source
- * projection to the destination projection.
+ * Searches in the list of transform functions for the function for converting
+ * coordinates from the source projection to the destination projection.
  *
- * @param {ol.proj.Projection} sourceProjection Source projection.
- * @param {ol.proj.Projection} destinationProjection Destination projection.
- * @return {ol.TransformFunction} Transform.
+ * @param {ol.proj.Projection} sourceProjection Source Projection object.
+ * @param {ol.proj.Projection} destinationProjection Destination Projection
+ *     object.
+ * @return {ol.TransformFunction} Transform function.
  */
 ol.proj.getTransformFromProjections =
     function(sourceProjection, destinationProjection) {
@@ -694,15 +699,20 @@ ol.proj.cloneTransform = function(input, opt_output, opt_dimension) {
 
 
 /**
- * @param {ol.Coordinate} point Point.
- * @param {ol.proj.ProjectionLike} source Source.
- * @param {ol.proj.ProjectionLike} destination Destination.
- * @return {ol.Coordinate} Point.
+ * Transforms a coordinate from source projection to destination projection.
+ * See {@link ol.extent.applyTransform} for extent transformation.
+ * See the applyTransform method of {@link ol.geom.SimpleGeometry} and its
+ * subclasses for geometry transforms.
+ *
+ * @param {ol.Coordinate} coordinate Coordinate.
+ * @param {ol.proj.ProjectionLike} source Source projection-like.
+ * @param {ol.proj.ProjectionLike} destination Destination projection-like.
+ * @return {ol.Coordinate} Coordinate.
  * @todo api
  */
-ol.proj.transform = function(point, source, destination) {
+ol.proj.transform = function(coordinate, source, destination) {
   var transformFn = ol.proj.getTransform(source, destination);
-  return transformFn(point);
+  return transformFn(coordinate);
 };
 
 

src/ol/proj/proj.jsdoc

@@ -1,3 +1,18 @@
 /**
+ * The ol.proj namespace stores:
+ * * a list of {@link ol.proj.Projection}
+ * objects, one for each projection supported by the application
+ * * a list of transform functions needed to convert coordinates in one projection
+ * into another.
+ *
+ * The static functions are the methods used to maintain these.
+ * Each transform function can handle not only simple coordinate pairs, but also
+ * large arrays of coordinates such as vector geometries.
+ *
+ * When loaded, the library adds projection objects for EPSG:4326 (WGS84
+ * geographic coordinates) and EPSG:3857 (Web or Spherical Mercator, as used
+ * for example by Bing Maps or OpenStreetMap), together with the relevant
+ * transform functions.
+ *
  * @namespace ol.proj
  */