From 87d651af04fdc95fd6878a34235ce56c82f0c909 Mon Sep 17 00:00:00 2001
From: Bart van den Eijnden <bartvde@boundlessgeo.com>
Date: Thu, 13 Feb 2014 13:23:04 +0100
Subject: [PATCH] Add documentation for API typedef functions

---
 src/ol/canvasfunction.js   | 9 +++++++++
 src/ol/coordinate.js       | 4 +++-
 src/ol/events/condition.js | 4 ++++
 src/ol/feature.js          | 9 +++++++++
 src/ol/tileloadfunction.js | 4 ++++
 src/ol/tileurlfunction.js  | 7 +++++++
 6 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/src/ol/canvasfunction.js b/src/ol/canvasfunction.js
index 202952effa..10caa4be88 100644
--- a/src/ol/canvasfunction.js
+++ b/src/ol/canvasfunction.js
@@ -2,7 +2,16 @@ goog.provide('ol.CanvasFunctionType');
 
 
 /**
+ * A function returning the canvas element (`{HTMLCanvasElement}`)
+ * used by the source as an image. The arguments passed to the function are:
+ * {@link ol.Extent} the image extent, `{number}` the image resolution,
+ * `{number}` the device pixel ratio, {@link ol.Size} the image size, and
+ * {@link ol.proj.Projection} the image projection. The canvas returned by
+ * this function is cached by the source. The this keyword inside the function
+ * references the {@link ol.source.ImageCanvas}.
+ *
  * @typedef {function(this:ol.source.ImageCanvas, ol.Extent, number,
  *     number, ol.Size, ol.proj.Projection): HTMLCanvasElement}
+ * @todo stability experimental
  */
 ol.CanvasFunctionType;
diff --git a/src/ol/coordinate.js b/src/ol/coordinate.js
index a965bcd75f..e027da504d 100644
--- a/src/ol/coordinate.js
+++ b/src/ol/coordinate.js
@@ -7,7 +7,9 @@ goog.require('goog.math');
 
 
 /**
- * A function that formats a {@link ol.Coordinate} into a string.
+ * A function that takes a {@link ol.Coordinate} and transforms it into a
+ * `{string}`.
+ *
  * @typedef {function((ol.Coordinate|undefined)): string}
  * @todo stability experimental
  */
diff --git a/src/ol/events/condition.js b/src/ol/events/condition.js
index dbedefbfdc..d6afa87bfc 100644
--- a/src/ol/events/condition.js
+++ b/src/ol/events/condition.js
@@ -8,7 +8,11 @@ goog.require('ol.MapBrowserEvent.EventType');
 
 
 /**
+ * A function that takes an {@link ol.MapBrowserEvent} and returns a
+ * `{boolean}`. If the condition is met, true should be returned.
+ *
  * @typedef {function(ol.MapBrowserEvent): boolean}
+ * @todo stability experimental
  */
 ol.events.ConditionType;
 
diff --git a/src/ol/feature.js b/src/ol/feature.js
index 54439b1b8c..68f36d1cec 100644
--- a/src/ol/feature.js
+++ b/src/ol/feature.js
@@ -203,6 +203,11 @@ ol.Feature.prototype.setGeometryName = function(name) {
 
 
 /**
+ * A function that takes a `{number}` representing the view's resolution. It
+ * returns an Array of {@link ol.style.Style}. This way individual features
+ * can be styled. The this keyword inside the function references the
+ * {@link ol.Feature} to be styled.
+ *
  * @typedef {function(this: ol.Feature, number): Array.<ol.style.Style>}
  * @todo stability experimental
  */
@@ -219,6 +224,10 @@ ol.feature.defaultFeatureStyleFunction = goog.functions.constant([]);
 
 
 /**
+ * A function that takes an {@link ol.Feature} and a `{number}` representing
+ * the view's resolution. The function should return an array of
+ * {@link ol.style.Style}. This way e.g. a vector layer can be styled.
+ *
  * @typedef {function(ol.Feature, number): Array.<ol.style.Style>}
  * @todo stability experimental
  */
diff --git a/src/ol/tileloadfunction.js b/src/ol/tileloadfunction.js
index f1f527066f..9524830044 100644
--- a/src/ol/tileloadfunction.js
+++ b/src/ol/tileloadfunction.js
@@ -2,6 +2,10 @@ goog.provide('ol.TileLoadFunctionType');
 
 
 /**
+ * A function that takes an {@link ol.ImageTile} for the image tile and a
+ * `{string}` for the src as arguments.
+ *
  * @typedef {function(ol.ImageTile, string)}
+ * @todo stability experimental
  */
 ol.TileLoadFunctionType;
diff --git a/src/ol/tileurlfunction.js b/src/ol/tileurlfunction.js
index ed7a17d9c3..0626f0ec80 100644
--- a/src/ol/tileurlfunction.js
+++ b/src/ol/tileurlfunction.js
@@ -7,8 +7,15 @@ goog.require('ol.TileCoord');
 
 
 /**
+ * A function that takes an {@link ol.TileCoord} for the tile coordinate,
+ * a `{number}` representing the pixel ratio and an {@link ol.proj.Projection}
+ * for the projection  as arguments and returns a `{string}` or
+ * undefined representing the tile URL. The this keyword inside the function
+ * references the {@link ol.source.TileImage}.
+ *
  * @typedef {function(this: ol.source.TileImage, ol.TileCoord,
  *     number, ol.proj.Projection): (string|undefined)}
+ * @todo stability experimental
  */
 ol.TileUrlFunctionType;