Doc changes suggested by @probins

examples/wms-custom-proj.js

@@ -8,14 +8,18 @@ goog.require('ol.proj');
 goog.require('ol.source.TileWMS');
 
 
-var proj4Def = proj4.defs['EPSG:21781'];
+// EPSG:21781 is known to Proj4js because its definition was loaded in the html.
 var projection = ol.proj.addProjection({
   code: '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/.
   extent: [485869.5728, 76443.1884, 837076.5648, 299941.7864],
-  units: proj4Def.units
+  // Use data from proj4js to configure the projection's units.
+  units: proj4.defs['EPSG:21781'].units
 });
+// Proj4js provides transform functions between its configured projections.
 // The transform is needed for the ScaleLine control. Otherwise this example
-// would also work without proj4js.
+// would also work without transform functions.
 ol.proj.addCoordinateTransforms('EPSG:4326', projection, proj4('EPSG:21781'));
 
 var extent = [420000, 30000, 900000, 350000];

examples/wms-image-custom-proj.js

@@ -8,8 +8,13 @@ goog.require('ol.proj');
 goog.require('ol.source.ImageWMS');
 
 
+// Transparent Proj4js support: ol.proj.get() creates and returns a projection
+// 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.
 var projection = ol.proj.get('EPSG:21781');
-// The extent is used to determine zoom level 0
+// The extent is used to determine zoom level 0. Recommended values for a
+// projection's validity extent can be found at http://epsg.io/.
 projection.setExtent([485869.5728, 76443.1884, 837076.5648, 299941.7864]);
 
 var extent = [420000, 30000, 900000, 350000];
@@ -51,9 +56,7 @@ var layers = [
 
 var map = new ol.Map({
   controls: ol.control.defaults().extend([
-    new ol.control.ScaleLine({
+    new ol.control.ScaleLine()
-      units: 'metric'
-    })
   ]),
   layers: layers,
   renderer: exampleNS.getRendererFromQueryString(),

externs/olx.js

@@ -284,7 +284,8 @@ olx.CoordinateTransforms;
 
 
 /**
- * The forward transform function that takes a {@link ol.Coordinate} as argument
+ * The forward transform function (that is, from the source projection to the
+ * target projection) that takes a {@link ol.Coordinate} as argument
  * and returns the transformed {@link ol.Coordinate}.
  * @type {function(ol.Coordinate): ol.Coordinate}
  */
@@ -292,7 +293,8 @@ olx.CoordinateTransforms.prototype.forward;
 
 
 /**
- * The inverse transform function that takes a {@link ol.Coordinate} as argument
+ * The inverse transform function (that is, from the target projection to the
+ * source projection) that takes a {@link ol.Coordinate} as argument
  * and returns the transformed {@link ol.Coordinate}.
  * @type {function(ol.Coordinate): ol.Coordinate}
  */

src/ol/proj/proj.js

@@ -62,7 +62,8 @@ ol.proj.METERS_PER_UNIT[ol.proj.Units.METERS] = 1;
  * 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.
+ * coordinate reference systems. Any transform functions can be added with
+ * {@link ol.proj.addCoordinateTransforms}.
  *
  * Additional transforms may be added by using the {@link http://proj4js.org/}
  * library. If the proj4js library is loaded, transforms will work between any