Improved documentation

src/ol/reproj/image.js

@@ -13,14 +13,19 @@ goog.require('ol.reproj.Triangulation');
 
 
 /**
+ * @classdesc
+ * Class encapsulating single reprojected image.
+ * See {@link ol.source.Image}.
+ *
  * @constructor
  * @extends {ol.ImageBase}
- * @param {ol.proj.Projection} sourceProj
+ * @param {ol.proj.Projection} sourceProj Source projection (of the data).
- * @param {ol.proj.Projection} targetProj
+ * @param {ol.proj.Projection} targetProj Target projection.
- * @param {ol.Extent} targetExtent
+ * @param {ol.Extent} targetExtent Target extent.
- * @param {number} targetResolution
+ * @param {number} targetResolution Target resolution.
- * @param {number} pixelRatio
+ * @param {number} pixelRatio Pixel ratio.
  * @param {function(ol.Extent, number, number):ol.ImageBase} getImageFunction
+ *     Function returning source images (extent, resolution, pixelRatio).
  */
 ol.reproj.Image = function(sourceProj, targetProj,
     targetExtent, targetResolution, pixelRatio, getImageFunction) {

src/ol/reproj/reproj.js

@@ -30,10 +30,10 @@ ol.reproj.browserAntialiasesClip_ = !goog.labs.userAgent.browser.isChrome() ||
  * The resolution is calculated regardless on what resolutions
  * are actually available in the dataset (TileGrid, Image, ...).
  *
- * @param {ol.proj.Projection} sourceProj
+ * @param {ol.proj.Projection} sourceProj Source projection.
- * @param {ol.proj.Projection} targetProj
+ * @param {ol.proj.Projection} targetProj Target projection.
- * @param {ol.Coordinate} targetCenter
+ * @param {ol.Coordinate} targetCenter Target center.
- * @param {number} targetResolution
+ * @param {number} targetResolution Target resolution.
  * @return {number} The best resolution to use. Can be +-Infinity, NaN or 0.
  */
 ol.reproj.calculateSourceResolution = function(sourceProj, targetProj,
@@ -73,34 +73,36 @@ ol.reproj.calculateSourceResolution = function(sourceProj, targetProj,
 /**
  * Enlarge the clipping triangle point by 1 pixel to ensure the edges overlap
  * in order to mask gaps caused by antialiasing.
- * @param {number} centroidX Centroid of the triangle.
+ *
- * @param {number} centroidY Centroid of the triangle.
+ * @param {number} centroidX Centroid of the triangle (x coordinate in pixels).
- * @param {number} u
+ * @param {number} centroidY Centroid of the triangle (y coordinate in pixels).
- * @param {number} v
+ * @param {number} x X coordinate of the point (in pixels).
- * @return {ol.Coordinate}
+ * @param {number} y Y coordinate of the point (in pixels).
+ * @return {ol.Coordinate} New point 1 px farther from the centroid.
  * @private
  */
-ol.reproj.enlargeClipPoint_ = function(centroidX, centroidY, u, v) {
+ol.reproj.enlargeClipPoint_ = function(centroidX, centroidY, x, y) {
-  var dX = u - centroidX, dY = v - centroidY;
+  var dX = x - centroidX, dY = y - centroidY;
   var distance = Math.sqrt(dX * dX + dY * dY);
-  return [Math.round(u + dX / distance), Math.round(v + dY / distance)];
+  return [Math.round(x + dX / distance), Math.round(y + dY / distance)];
 };
 
 
 /**
- * Renders the source into the canvas based on the triangulation.
+ * Renders the source data into new canvas based on the triangulation.
- * @param {number} width
+ *
- * @param {number} height
+ * @param {number} width Width of the canvas.
- * @param {number} pixelRatio
+ * @param {number} height Height of the canvas.
- * @param {number} sourceResolution
+ * @param {number} pixelRatio Pixel ratio.
- * @param {ol.Extent} sourceExtent
+ * @param {number} sourceResolution Source resolution.
- * @param {number} targetResolution
+ * @param {ol.Extent} sourceExtent Extent of the data source.
- * @param {ol.Extent} targetExtent
+ * @param {number} targetResolution Target resolution.
- * @param {ol.reproj.Triangulation} triangulation
+ * @param {ol.Extent} targetExtent Target extent.
+ * @param {ol.reproj.Triangulation} triangulation Calculated triangulation.
  * @param {Array.<{extent: ol.Extent,
- *                 image: (HTMLCanvasElement|Image)}>} sources
+ *                 image: (HTMLCanvasElement|Image)}>} sources Array of sources.
- * @param {boolean=} opt_renderEdges
+ * @param {boolean=} opt_renderEdges Render reprojection edges.
- * @return {HTMLCanvasElement}
+ * @return {HTMLCanvasElement} Canvas with reprojected data.
  */
 ol.reproj.render = function(width, height, pixelRatio,
     sourceResolution, sourceExtent, targetResolution, targetExtent,

src/ol/reproj/tile.js

@@ -16,19 +16,24 @@ goog.require('ol.reproj.Triangulation');
 
 
 /**
+ * @classdesc
+ * Class encapsulating single reprojected tile.
+ * See {@link ol.source.TileImage}.
+ *
  * @constructor
  * @extends {ol.Tile}
- * @param {ol.proj.Projection} sourceProj
+ * @param {ol.proj.Projection} sourceProj Source projection.
- * @param {ol.tilegrid.TileGrid} sourceTileGrid
+ * @param {ol.tilegrid.TileGrid} sourceTileGrid Source tile grid.
- * @param {ol.proj.Projection} targetProj
+ * @param {ol.proj.Projection} targetProj Target projection.
- * @param {ol.tilegrid.TileGrid} targetTileGrid
+ * @param {ol.tilegrid.TileGrid} targetTileGrid Target tile grid.
- * @param {number} z
+ * @param {number} z Zoom level.
- * @param {number} x
+ * @param {number} x X.
- * @param {number} y
+ * @param {number} y Y.
- * @param {number} pixelRatio
+ * @param {number} pixelRatio Pixel ratio.
  * @param {function(number, number, number, number) : ol.Tile} getTileFunction
- * @param {number=} opt_errorThreshold
+ *     Function returning source tiles (z, x, y, pixelRatio).
- * @param {boolean=} opt_renderEdges
+ * @param {number=} opt_errorThreshold Acceptable reprojection error (in px).
+ * @param {boolean=} opt_renderEdges Render reprojection edges.
  */
 ol.reproj.Tile = function(sourceProj, sourceTileGrid,
     targetProj, targetTileGrid, z, x, y, pixelRatio, getTileFunction,

src/ol/reproj/triangulation.js

@@ -18,10 +18,14 @@ ol.reproj.Triangle;
 
 
 /**
- * @param {ol.proj.Projection} sourceProj
+ * @classdesc
- * @param {ol.proj.Projection} targetProj
+ * Class containing triangulation of the given target extent.
- * @param {ol.Extent} targetExtent
+ * Used for determining source data and the reprojection itself.
- * @param {ol.Extent} maxSourceExtent
+ *
+ * @param {ol.proj.Projection} sourceProj Source projection.
+ * @param {ol.proj.Projection} targetProj Target projection.
+ * @param {ol.Extent} targetExtent Target extent to triangulate.
+ * @param {ol.Extent} maxSourceExtent Maximal source extent that can be used.
  * @param {number} errorThreshold Acceptable error (in source units).
  * @constructor
  */
@@ -150,6 +154,8 @@ ol.reproj.Triangulation.prototype.addTriangle_ = function(a, b, c,
 /**
  * Adds quad (points in clock-wise order) to the triangulation
  * (and reprojects the vertices) if valid.
+ * Performs quad subdivision if needed to increase precision.
+ *
  * @param {ol.Coordinate} a
  * @param {ol.Coordinate} b
  * @param {ol.Coordinate} c
@@ -264,7 +270,12 @@ ol.reproj.Triangulation.prototype.addQuad_ = function(a, b, c, d,
 
 
 /**
- * @return {ol.Extent}
+ * Calculates extent of the 'source' coordinates from all the triangles.
+ * The left bound of the returned extent can be higher than the right bound,
+ * if the triangulation wraps X in source (see
+ * {@link ol.reproj.Triangulation#getWrapsXInSource}).
+ *
+ * @return {ol.Extent} Calculated extent.
  */
 ol.reproj.Triangulation.prototype.calculateSourceExtent = function() {
   if (!goog.isNull(this.trianglesSourceExtent_)) {
@@ -312,7 +323,8 @@ ol.reproj.Triangulation.prototype.calculateSourceExtent = function() {
 
 
 /**
- * @return {boolean}
+ * @return {boolean} Whether the source coordinates are wrapped in X
+ *                   (the triangulation "crosses the dateline").
  */
 ol.reproj.Triangulation.prototype.getWrapsXInSource = function() {
   return this.wrapsXInSource_;
@@ -320,7 +332,7 @@ ol.reproj.Triangulation.prototype.getWrapsXInSource = function() {
 
 
 /**
- * @return {Array.<ol.reproj.Triangle>}
+ * @return {Array.<ol.reproj.Triangle>} Array of the calculated triangles.
  */
 ol.reproj.Triangulation.prototype.getTriangles = function() {
   return this.triangles_;

src/ol/source/tileimagesource.js

@@ -303,7 +303,7 @@ ol.source.TileImage.prototype.handleTileChange_ = function(event) {
 
 /**
  * Sets whether to render reprojection edges or not (usually for debugging).
- * @param {boolean} render
+ * @param {boolean} render Render the edges.
  * @api
  */
 ol.source.TileImage.prototype.setRenderReprojectionEdges = function(render) {
@@ -317,8 +317,15 @@ ol.source.TileImage.prototype.setRenderReprojectionEdges = function(render) {
 
 
 /**
- * @param {ol.proj.ProjectionLike} projection
+ * Sets the tile grid to use when reprojecting the tiles to the given
- * @param {ol.tilegrid.TileGrid} tilegrid
+ * projection instead of the default tile grid for the projection.
+ *
+ * This can be useful when the default tile grid cannot be created
+ * (e.g. projection has no extent defined) or
+ * for optimization reasons (custom tile size, resolutions, ...).
+ *
+ * @param {ol.proj.ProjectionLike} projection Projection.
+ * @param {ol.tilegrid.TileGrid} tilegrid Tile grid to use for the projection.
  * @api
  */
 ol.source.TileImage.prototype.setTileGridForProjection =

src/ol/source/tilesource.js

@@ -98,7 +98,7 @@ ol.source.Tile.prototype.canExpireCache = function() {
 
 
 /**
- * @param {ol.proj.Projection} projection
+ * @param {ol.proj.Projection} projection Projection.
  * @param {Object.<string, ol.TileRange>} usedTiles Used tiles.
  */
 ol.source.Tile.prototype.expireCache = function(projection, usedTiles) {
@@ -110,7 +110,7 @@ ol.source.Tile.prototype.expireCache = function(projection, usedTiles) {
 
 
 /**
- * @param {ol.proj.Projection} projection
+ * @param {ol.proj.Projection} projection Projection.
  * @param {number} z Zoom level.
  * @param {ol.TileRange} tileRange Tile range.
  * @param {function(ol.Tile):(boolean|undefined)} callback Called with each
@@ -231,7 +231,7 @@ ol.source.Tile.prototype.getTileCacheForProjection = function(projection) {
 
 
 /**
- * @return {number}
+ * @return {number} Tile pixel ratio.
  */
 ol.source.Tile.prototype.getTilePixelRatio = function() {
   return this.tilePixelRatio_;