From 8c4c83b20772affcdc076e9e6b81cae02e24e4da Mon Sep 17 00:00:00 2001
From: Paul Spencer <paul@pagameba.com>
Date: Fri, 30 Aug 2013 11:32:47 -0400
Subject: [PATCH] Improve documentation for animation-related stuff

The animation-related code is missing sufficient detail to make it
usable without digging in to the code.  This adds some additional
detail to the ol.animation namespace, the related options, and makes
note of the existance of ol.animation in the documentation of
ol.Map.addPreRenderFunction(s).
---
 src/objectliterals.jsdoc | 20 ++++++++++----------
 src/ol/animation.jsdoc   |  9 +++++++++
 src/ol/map.js            |  5 +++--
 3 files changed, 22 insertions(+), 12 deletions(-)

diff --git a/src/objectliterals.jsdoc b/src/objectliterals.jsdoc
index 8b94acbd1f..74faeefaf4 100644
--- a/src/objectliterals.jsdoc
+++ b/src/objectliterals.jsdoc
@@ -119,31 +119,31 @@
 
 /**
  * @typedef {Object} ol.animation.BounceOptions
- * @property {number} resolution Resolution.
+ * @property {number} resolution The resolution to start the bounce from, typically `map.getView().getResolution()`.
  * @property {number|undefined} start The start time of the animation. Default is immediately.
- * @property {number|undefined} duration The duration of the animation in milliseconds.
- * @property {function(number):number|undefined} easing Easing function.
+ * @property {number|undefined} duration The duration of the animation in milliseconds. Default is 1000.
+ * @property {function(number):number|undefined} easing The easing function to use.  Default is `ol.easing.inAndOut`
  */
 
 /**
  * @typedef {Object} ol.animation.PanOptions
- * @property {ol.Coordinate} source Source.
+ * @property {ol.Coordinate} source The location to start panning from, typically `map.getView().getCenter()`.
  * @property {number|undefined} start The start time of the animation. Default is immediately.
- * @property {number|undefined} duration The duration of the animation in milliseconds.
- * @property {function(number):number|undefined} easing Easing function.
+ * @property {number|undefined} duration The duration of the animation in milliseconds. Default is 1000.
+ * @property {function(number):number|undefined} easing The easing function to use.  Default is `ol.easing.inAndOut`
  */
 
 /**
  * @typedef {Object} ol.animation.RotateOptions
- * @property {number} rotation Rotation.
+ * @property {number} rotation The rotation to apply, in radians.
  * @property {number|undefined} start The start time of the animation. Default is immediately.
- * @property {number|undefined} duration The duration of the animation in milliseconds.
- * @property {function(number):number|undefined} easing Easing function.
+ * @property {number|undefined} duration The duration of the animation in milliseconds.  Default is 1000.
+ * @property {function(number):number|undefined} easing The easing function to use.  Default is `ol.easing.inAndOut`
  */
 
 /**
  * @typedef {Object} ol.animation.ZoomOptions
- * @property {number} resolution number Resolution.
+ * @property {number} resolution number The resolution to begin zooming from, typically `map.getView().getResolution()`.
  * @property {number|undefined} start The start time of the animation. Default is immediately.
  * @property {number|undefined} duration The duration of the animation in milliseconds.
  * @property {function(number):number|undefined} easing Easing function.
diff --git a/src/ol/animation.jsdoc b/src/ol/animation.jsdoc
index 5ee3f363a0..0f1fac89e2 100644
--- a/src/ol/animation.jsdoc
+++ b/src/ol/animation.jsdoc
@@ -1,3 +1,12 @@
 /**
+ * The {ol.animation} static methods are designed to be used with the {@link ol.Map#addPreRenderFunction} and {@link ol.Map#addPreRenderFunctions} methods.  For example:
+ *
+ *     var map = new ol.Map({ ... });
+ *     var zoom = ol.animation.zoom({
+ *       resolution: map.getView().getResolution()
+ *     });
+ *     map.addPreRenderFunction(zoom);
+ *     map.getView().setResolution(map.getView().getResolution() * 2);
+ *
  * @namespace ol.animation
  */
diff --git a/src/ol/map.js b/src/ol/map.js
index 8fa48bedfe..20a16ed3e1 100644
--- a/src/ol/map.js
+++ b/src/ol/map.js
@@ -363,7 +363,8 @@ ol.Map.prototype.addLayer = function(layer) {
 
 /**
  * Add a prerender function. This can be used for attaching animations to
- * be performed before setting the map's center.
+ * be performed before setting the map's center.  The {@link ol.animation} 
+ * namespace provides several static methods for creating prerender functions.
  * @param {ol.PreRenderFunction} preRenderFunction Pre-render function.
  */
 ol.Map.prototype.addPreRenderFunction = function(preRenderFunction) {
@@ -374,7 +375,7 @@ ol.Map.prototype.addPreRenderFunction = function(preRenderFunction) {
 
 /**
  * Add prerender functions. This can be used for attaching animations to
- * be performed before setting the map's center.
+ * be performed before setting the map's center.  See {@link ol.animation}
  * @param {Array.<ol.PreRenderFunction>} preRenderFunctions
  *     Pre-render functions.
  */