Improve docs for projection

examples/wms-image-custom-proj.js

@@ -12,6 +12,10 @@ goog.require('ol.source.ImageWMS');
 // known to Proj4js if it is unknown to OpenLayers, and registers functions to
 // transform between all registered projections.
 // EPSG:21781 is known to Proj4js because its definition was loaded in the html.
+// Note that we are getting the projection object here to set the extent. If
+// you do not need this, you do not have to use ol.proj.get(); simply use the
+// string code in the view projection below and the transforms will be
+// registered transparently.
 var projection = ol.proj.get('EPSG:21781');
 // The extent is used to determine zoom level 0. Recommended values for a
 // projection's validity extent can be found at http://epsg.io/.

examples/wms-no-proj.js

@@ -42,8 +42,10 @@ var layers = [
 ];
 
 // A minimal projection object is configured with only the SRS code and the map
-// units. No client side coordinate transforms are possible with such a
-// projection object.
+// units. No client-side coordinate transforms are possible with such a
+// projection object. Requesting tiles only needs the code together with a
+// tile grid of Cartesian coordinates; it does not matter how those
+// coordinates relate to latitude or longitude.
 var projection = new ol.proj.Projection({
   code: 'EPSG:21781',
   units: 'm'

src/ol/proj/proj.js

@@ -51,16 +51,14 @@ ol.proj.METERS_PER_UNIT[ol.proj.Units.METERS] = 1;
 
 /**
  * @classdesc
- * Class for coordinate transforms between coordinate systems. By default,
- * OpenLayers ships with the ability to transform coordinates between
- * geographic (EPSG:4326) and web or spherical mercator (EPSG:3857)
- * coordinate reference systems. Any transform functions can be added with
- * {@link ol.proj.addCoordinateTransforms}.
+ * Projection definition class. One of these is created for each projection
+ * supported in the application and stored in the {@link ol.proj} namespace.
+ * You can use these in applications, but this is not required, as API params
+ * and options use {@link ol.proj.ProjectionLike} which means the simple string
+ * code will suffice.
  *
- * Additional transforms may be added by using the {@link http://proj4js.org/}
- * library. If the proj4js library is loaded, transforms will work between any
- * coordinate reference systems with proj4js definitions. These definitions can
- * be obtained from {@link http://epsg.io/}.
+ * You can use {@link ol.proj.get} to retrieve the object for a particular
+ * projection.
  *
  * @constructor
  * @param {olx.ProjectionOptions} options Projection options.
@@ -368,6 +366,9 @@ ol.proj.addTransform = function(source, destination, transformFn) {
 /**
  * Registers coordinate transform functions to convert coordinates between the
  * source projection and the destination projection.
+ * The forward and inverse functions convert coordinate pairs; this function
+ * converts these into the functions used internally which also handle
+ * extents and coordinate arrays.
  *
  * @param {ol.proj.ProjectionLike} source Source projection.
  * @param {ol.proj.ProjectionLike} destination Destination projection.

src/ol/proj/proj.jsdoc

@@ -14,5 +14,41 @@
  * for example by Bing Maps or OpenStreetMap), together with the relevant
  * transform functions.
  *
+ * Additional transforms may be added by using the {@link http://proj4js.org/}
+ * library (version 2.2 or later). You can use the full build supplied by
+ * Proj4js, or create a custom build to support those projections you need; see
+ * the Proj4js website for how to do this. You also need the Proj4js definitions
+ * for the required projections. These definitions can be obtained from
+ * {@link http://epsg.io/}, and are a JS function, so can be loaded in a script
+ * tag (as in the examples) or pasted into your application.
+ * The first time there is a request for a projection, either with a
+ * {@link ol.proj.projectionLike} or directly with {@link ol.proj.get}, the
+ * code will check if the Proj4js library and the necessary definition are
+ * loaded; if so, it will register the appropriate {@link ol.proj.Projection}
+ * object and add transform functions between the new projection and all the
+ * existing ones. See examples/wms-image-custom-proj for an example of this.
+ * Because the check for presence of the Proj4js library and the definition only
+ * takes place on the first request for them, this means they can be loaded
+ * dynamically as needed; for example, with user-supplied data where you don't
+ * know in advance what projections are needed, you can initially load minimal
+ * support and then load whichever are requested.
+ *
+ * Note that Proj4js does not support projection extents. If you want to add
+ * one for creating default tile grids, you can add it after the Projection
+ * object has been created with `setExtent`, for example,
+ * `ol.proj.get('EPSG:1234').setExtent(extent)`.
+ *
+ * In addition to Proj4js support, any transform functions can be added with
+ * {@link ol.proj.addCoordinateTransforms}. To use this, you must first create
+ * a {@link ol.proj.Projection} object for the new projection and add it with
+ * {@link ol.proj.addProjection}. You can then add the forward and inverse
+ * functions with {@link ol.proj.addCoordinateTransforms}. See
+ * examples/wms-custom-proj for an example of this.
+ *
+ * Note that if no transforms are needed and you only need to define the
+ * projection, just add a {@link ol.proj.Projection} with
+ * {@link ol.proj.addProjection}. See examples/wms-no-proj for an example of
+ * this.
+ *
  * @namespace ol.proj
  */