From 8dc97790bc2735bbb00755350a3e0b3d7b4b7635 Mon Sep 17 00:00:00 2001
From: Bart van den Eijnden <bartvde@opengeo.org>
Date: Tue, 11 Jun 2013 11:09:39 +0200
Subject: [PATCH 1/2] Add more content for the API doc

Involves additions to (there will be subsequent pull requests for other
classes):
- ol.Attribution
- ol.Collection
- ol.Expression
- ol.Feature
- ol.Geolocation
- ol.Map
- ol.Object
- ol.Overlay
- ol.Projection
- ol.View2D
- ol.control.Attribution
- ol.control.Control
- ol.control.FullScreen
- ol.control.Logo
- ol.control.MousePosition
- ol.control.ScaleLine
- ol.control.Zoom
- ol.control.ZoomSlider
- ol.dom.Input
- ol.filter.Filter
- ol.filter.Geometry
- ol.filter.Logical
---
 src/ol/attribution.js                  | 18 ++++++++++++--
 src/ol/collection.js                   | 16 +++++++++++--
 src/ol/control/attributioncontrol.js   |  4 ++++
 src/ol/control/control.js              |  5 ++--
 src/ol/control/fullscreencontrol.js    | 11 +++++++++
 src/ol/control/logocontrol.js          |  4 ++++
 src/ol/control/mousepositioncontrol.js | 13 ++++++++++
 src/ol/control/scalelinecontrol.js     | 12 ++++++++++
 src/ol/control/zoomcontrol.js          |  3 +++
 src/ol/control/zoomslidercontrol.js    |  8 +++++++
 src/ol/dom/input.js                    | 12 ++++++++++
 src/ol/expression.js                   | 10 ++++++++
 src/ol/feature.js                      | 14 ++++++++++-
 src/ol/filter.jsdoc                    |  3 +++
 src/ol/filter/filter.js                | 12 ++++++++++
 src/ol/filter/geometryfilter.js        |  1 +
 src/ol/filter/logicalfilter.js         | 13 +++++++++-
 src/ol/geolocation.js                  | 33 ++++++++++++++++++++++----
 src/ol/map.js                          | 18 ++++++++++++++
 src/ol/object.js                       | 16 +++++++++++++
 src/ol/overlay.js                      | 17 +++++++++++++
 src/ol/proj/proj.js                    | 17 +++++++++++++
 src/ol/view2d.js                       | 18 +++++++++++++-
 23 files changed, 264 insertions(+), 14 deletions(-)
 create mode 100644 src/ol/filter.jsdoc

diff --git a/src/ol/attribution.js b/src/ol/attribution.js
index f162f317d1..81a88007be 100644
--- a/src/ol/attribution.js
+++ b/src/ol/attribution.js
@@ -5,9 +5,23 @@ goog.require('ol.TileRange');
 
 
 /**
+ * Create a new attribution to be associated with a layer source.
+ *
+ * Example:
+ *
+ *     source: new ol.source.OSM({
+ *       attributions: [
+ *       new ol.Attribution(
+ *         'All maps &copy; ' +
+ *         '<a href="http://www.opencyclemap.org/">OpenCycleMap</a>'),
+ *       ol.source.OSM.DATA_ATTRIBUTION
+ *     ],
+ *     ..
+ *
  * @constructor
- * @param {string} html HTML.
- * @param {Object.<string, Array.<ol.TileRange>>=} opt_tileRanges Tile ranges.
+ * @param {string} html The markup to use for display of the attribution.
+ * @param {Object.<string, Array.<ol.TileRange>>=} opt_tileRanges Tile ranges
+ *     (FOR INTERNAL USE ONLY).
  */
 ol.Attribution = function(html, opt_tileRanges) {
 
diff --git a/src/ol/collection.js b/src/ol/collection.js
index 147e03abac..fb3fd57962 100644
--- a/src/ol/collection.js
+++ b/src/ol/collection.js
@@ -53,6 +53,7 @@ ol.CollectionProperty = {
 
 
 /**
+ * A mutable MVC Array.
  * @constructor
  * @extends {ol.Object}
  * @param {Array=} opt_array Array.
@@ -95,8 +96,12 @@ ol.Collection.prototype.extend = function(arr) {
 
 
 /**
- * @param {Function} f Function.
- * @param {Object=} opt_obj Object.
+ * Iterate over each element, calling the provided callback.
+ * @param {Function} f The function to call for every element. This function
+ *     takes 3 arguments (the element, the index and the array). The return
+ *     value is ignored.
+ * @param {Object=} opt_obj The object to be used as the value of 'this'
+ *     within f.
  */
 ol.Collection.prototype.forEach = function(f, opt_obj) {
   goog.array.forEach(this.array_, f, opt_obj);
@@ -112,6 +117,7 @@ ol.Collection.prototype.getArray = function() {
 
 
 /**
+ * Get the element at the provided index.
  * @param {number} index Index.
  * @return {*} Element.
  */
@@ -121,6 +127,7 @@ ol.Collection.prototype.getAt = function(index) {
 
 
 /**
+ * Get the length of this collection.
  * @return {number} Length.
  */
 ol.Collection.prototype.getLength = function() {
@@ -129,6 +136,7 @@ ol.Collection.prototype.getLength = function() {
 
 
 /**
+ * Insert an element at the provided index.
  * @param {number} index Index.
  * @param {*} elem Element.
  */
@@ -141,6 +149,7 @@ ol.Collection.prototype.insertAt = function(index, elem) {
 
 
 /**
+ * Remove the last element of the collection.
  * @return {*} Element.
  */
 ol.Collection.prototype.pop = function() {
@@ -149,6 +158,7 @@ ol.Collection.prototype.pop = function() {
 
 
 /**
+ * Insert the provided element at the end of the collection.
  * @param {*} elem Element.
  * @return {number} Length.
  */
@@ -177,6 +187,7 @@ ol.Collection.prototype.remove = function(elem) {
 
 
 /**
+ * Remove the element at the provided index.
  * @param {number} index Index.
  * @return {*} Value.
  */
@@ -191,6 +202,7 @@ ol.Collection.prototype.removeAt = function(index) {
 
 
 /**
+ * Set the element at the provided index.
  * @param {number} index Index.
  * @param {*} elem Element.
  */
diff --git a/src/ol/control/attributioncontrol.js b/src/ol/control/attributioncontrol.js
index 701cf77095..6b131d1596 100644
--- a/src/ol/control/attributioncontrol.js
+++ b/src/ol/control/attributioncontrol.js
@@ -18,6 +18,10 @@ goog.require('ol.source.Source');
 
 
 /**
+ * Create a new attribution control to show all the attributions associated
+ * with the layer sources in the map. A default map has this control included.
+ * By default it will show in the bottom right portion of the map, but it can
+ * be changed by using a css selector for .ol-attribution.
  * @constructor
  * @extends {ol.control.Control}
  * @param {ol.control.AttributionOptions=} opt_options Attribution options.
diff --git a/src/ol/control/control.js b/src/ol/control/control.js
index e63ba7671a..a8dd7c312a 100644
--- a/src/ol/control/control.js
+++ b/src/ol/control/control.js
@@ -9,8 +9,8 @@ goog.require('ol.MapEventType');
 
 
 /**
- * A thing which is painted over the map to provide a means for interaction
- * (buttons) of show annotations (status bars).
+ * Something to be painted over the map to provide a means for interaction
+ * (buttons) or to show annotations (status bars).
  *
  * @constructor
  * @extends {goog.Disposable}
@@ -63,6 +63,7 @@ ol.control.Control.prototype.disposeInternal = function() {
 
 
 /**
+ * Get the map associated with this control.
  * @return {ol.Map} Map.
  */
 ol.control.Control.prototype.getMap = function() {
diff --git a/src/ol/control/fullscreencontrol.js b/src/ol/control/fullscreencontrol.js
index e35049c532..070be30f44 100644
--- a/src/ol/control/fullscreencontrol.js
+++ b/src/ol/control/fullscreencontrol.js
@@ -14,6 +14,17 @@ goog.require('ol.css');
 
 
 /**
+ * Provides a button that when clicked fills up the full screen with the map.
+ * When in full screen mode, a close button is shown to exit full screen mode.
+ *
+ * Example:
+ *
+ *     var map = new ol.Map({
+ *       controls: ol.control.defaults({}, [
+ *         new ol.control.FullScreen()
+ *       ]),
+ *       ...
+ *
  * @constructor
  * @extends {ol.control.Control}
  * @param {ol.control.FullScreenOptions=} opt_options Options.
diff --git a/src/ol/control/logocontrol.js b/src/ol/control/logocontrol.js
index 7638846cc8..6237d4bed1 100644
--- a/src/ol/control/logocontrol.js
+++ b/src/ol/control/logocontrol.js
@@ -11,6 +11,10 @@ goog.require('ol.css');
 
 
 /**
+ * Shows a logo for all the layer sources in the map that have a logo
+ * associated with them, such as Bing. This control is part of a default map.
+ * By default it will show in the bottom-left portion of the map, but it can
+ * be styled by using a css selector for .ol-logo.
  * @constructor
  * @extends {ol.control.Control}
  * @param {ol.control.LogoOptions=} opt_options Logo options.
diff --git a/src/ol/control/mousepositioncontrol.js b/src/ol/control/mousepositioncontrol.js
index 9e848c9b80..0e1d220b2c 100644
--- a/src/ol/control/mousepositioncontrol.js
+++ b/src/ol/control/mousepositioncontrol.js
@@ -19,6 +19,19 @@ goog.require('ol.proj');
 
 
 /**
+ * Create a new control to show the position of the mouse in the map's
+ * projection (or any other supplied projection). By default the control is
+ * shown in the top right corner of the map but this can be changed by using
+ * a css selector .ol-mouse-position.
+ *
+ * Example:
+ *
+ *     var map = new ol.Map({
+ *       controls: ol.control.defaults({}, [
+ *         new ol.control.MousePosition({projection: ol.proj.get('EPSG:4326')})
+ *       ]),
+ *       ...
+ *
  * @constructor
  * @extends {ol.control.Control}
  * @param {ol.control.MousePositionOptions=} opt_options Mouse position options.
diff --git a/src/ol/control/scalelinecontrol.js b/src/ol/control/scalelinecontrol.js
index b7fe8fe411..7c3d76c913 100644
--- a/src/ol/control/scalelinecontrol.js
+++ b/src/ol/control/scalelinecontrol.js
@@ -30,6 +30,18 @@ ol.control.ScaleLineUnits = {
 
 
 /**
+ * Create a control to help users estimate distances on a map.
+ *
+ * Example:
+ *
+ *     var map = new ol.Map({
+ *       controls: ol.control.defaults({}, [
+ *         new ol.control.ScaleLine({
+ *           units: ol.control.ScaleLineUnits.IMPERIAL
+ *         })
+ *       ]),
+ *       ...
+ *
  * @constructor
  * @extends {ol.control.Control}
  * @param {ol.control.ScaleLineOptions=} opt_options Scale line options.
diff --git a/src/ol/control/zoomcontrol.js b/src/ol/control/zoomcontrol.js
index 89b5edc30a..74c24cdd11 100644
--- a/src/ol/control/zoomcontrol.js
+++ b/src/ol/control/zoomcontrol.js
@@ -20,6 +20,9 @@ ol.control.ZOOM_DURATION = 250;
 
 
 /**
+ * Create a new control with 2 buttons, one for zoom in and one for zoom out.
+ * This control is part of the default controls of a map. To style this control
+ * use css selectors .ol-zoom-in and .ol-zoom-out.
  * @constructor
  * @extends {ol.control.Control}
  * @param {ol.control.ZoomOptions=} opt_options Zoom options.
diff --git a/src/ol/control/zoomslidercontrol.js b/src/ol/control/zoomslidercontrol.js
index 4c6908d2c6..e324eab6a6 100644
--- a/src/ol/control/zoomslidercontrol.js
+++ b/src/ol/control/zoomslidercontrol.js
@@ -29,6 +29,14 @@ ol.control.ZOOMSLIDER_ANIMATION_DURATION = 200;
 
 
 /**
+ * A slider type of control for zooming.
+ *
+ * Example:
+ *
+ *     var zoomslider = new ol.control.ZoomSlider({
+ *       map: map
+ *     });
+ *
  * @constructor
  * @extends {ol.control.Control}
  * @param {ol.control.ZoomSliderOptions=} opt_options Zoom slider options.
diff --git a/src/ol/dom/input.js b/src/ol/dom/input.js
index 9202b7550f..6e697d877d 100644
--- a/src/ol/dom/input.js
+++ b/src/ol/dom/input.js
@@ -17,6 +17,14 @@ ol.dom.InputProperty = {
 
 
 /**
+ * Helper class for binding HTML input to an ol.Object
+ *
+ * Example:
+ *
+ *     // bind a checkbox with id 'visible' to a layer's visibility
+ *     var visible = new ol.dom.Input(document.getElementById('visible'));
+ *     visible.bindTo('checked', layer, 'visible');
+ *
  * @constructor
  * @extends {ol.Object}
  * @param {Element} target Target element.
@@ -44,6 +52,7 @@ goog.inherits(ol.dom.Input, ol.Object);
 
 
 /**
+ * If the input is a checkbox, return whether or not the checbox is checked.
  * @return {boolean|undefined} checked.
  */
 ol.dom.Input.prototype.getChecked = function() {
@@ -56,6 +65,7 @@ goog.exportProperty(
 
 
 /**
+ * Get the value of the input.
  * @return {string|undefined} input value.
  */
 ol.dom.Input.prototype.getValue = function() {
@@ -68,6 +78,7 @@ goog.exportProperty(
 
 
 /**
+ * Sets the value of the input.
  * @param {string} value Value.
  */
 ol.dom.Input.prototype.setValue = function(value) {
@@ -80,6 +91,7 @@ goog.exportProperty(
 
 
 /**
+ * Set whether or not a checkbox is checked.
  * @param {boolean} checked Checked.
  */
 ol.dom.Input.prototype.setChecked = function(checked) {
diff --git a/src/ol/expression.js b/src/ol/expression.js
index 4adf62be27..7b1370ae0d 100644
--- a/src/ol/expression.js
+++ b/src/ol/expression.js
@@ -4,6 +4,16 @@ goog.provide('ol.ExpressionLiteral');
 
 
 /**
+ * Create a new expression. Expressions are used for instance to bind
+ * symbolizer properties to feature attributes.
+ *
+ * Example:
+ *
+ *     // take the color from the color attribute
+ *     color: new ol.Expression('color');
+ *     // take the strokeWidth from the width attribute and multiply by 2.
+ *     strokeWidth: new ol.Expression('width*2');
+ *
  * @constructor
  * @param {string} source Expression to be evaluated.
  */
diff --git a/src/ol/feature.js b/src/ol/feature.js
index 3430e109de..98895fe593 100644
--- a/src/ol/feature.js
+++ b/src/ol/feature.js
@@ -6,6 +6,14 @@ goog.require('ol.geom.Geometry');
 
 
 /**
+ * Create a new feature. A feature is the base entity for vectors and has
+ * attributes, including normally a geometry attribute.
+ *
+ * Example:
+ *
+ *     var feature = new ol.Feature({'foo': 'bar'});
+ *     feature.setGeometry(new ol.geom.Point([100, 500]));
+ *
  * @constructor
  * @extends {ol.Object}
  * @param {Object.<string, *>=} opt_values Attributes.
@@ -37,6 +45,7 @@ goog.inherits(ol.Feature, ol.Object);
 
 
 /**
+ * Gets a copy of the attributes of this feature.
  * @return {Object.<string, *>} Attributes object.
  */
 ol.Feature.prototype.getAttributes = function() {
@@ -64,6 +73,7 @@ ol.Feature.prototype.getFeatureId = function() {
 
 
 /**
+ * Get the geometry associated with this feature.
  * @return {ol.geom.Geometry} The geometry (or null if none).
  */
 ol.Feature.prototype.getGeometry = function() {
@@ -114,6 +124,7 @@ ol.Feature.prototype.setFeatureId = function(featureId) {
 
 
 /**
+ * Set the geometry to be associated with this feature after its creation.
  * @param {ol.geom.Geometry} geometry The geometry.
  */
 ol.Feature.prototype.setGeometry = function(geometry) {
@@ -125,8 +136,9 @@ ol.Feature.prototype.setGeometry = function(geometry) {
 
 
 /**
+ * Set the symbolizers to be used for this feature.
  * @param {Array.<ol.style.Symbolizer>} symbolizers Symbolizers for this
- *     features. If set, these take precedence over layer style.
+ *     feature. If set, these take precedence over layer style.
  */
 ol.Feature.prototype.setSymbolizers = function(symbolizers) {
   this.symbolizers_ = symbolizers;
diff --git a/src/ol/filter.jsdoc b/src/ol/filter.jsdoc
new file mode 100644
index 0000000000..b9fad2900f
--- /dev/null
+++ b/src/ol/filter.jsdoc
@@ -0,0 +1,3 @@
+/**
+ * @namespace ol.filter
+ */
diff --git a/src/ol/filter/filter.js b/src/ol/filter/filter.js
index 701a942ae7..0d37a211dd 100644
--- a/src/ol/filter/filter.js
+++ b/src/ol/filter/filter.js
@@ -5,6 +5,18 @@ goog.require('ol.Feature');
 
 
 /**
+ * Create a new filter which can be used to filter features based on a
+ * function.
+ *
+ * Example:
+ *
+ *     new ol.style.Rule({
+ *       filter: new ol.filter.Filter(function(feature) {
+ *         return feature.get('where') == 'outer';
+ *       }),
+ *       symbolizers: [
+ *         ...
+ *
  * @constructor
  * @param {function(this:ol.filter.Filter, ol.Feature)=} opt_filterFunction
  *     Filter function. Should return true if the passed feature passes the
diff --git a/src/ol/filter/geometryfilter.js b/src/ol/filter/geometryfilter.js
index 979ae37741..1f6707f7e3 100644
--- a/src/ol/filter/geometryfilter.js
+++ b/src/ol/filter/geometryfilter.js
@@ -7,6 +7,7 @@ goog.require('ol.geom.GeometryType');
 
 
 /**
+ * Filter features by geometry type.
  * @constructor
  * @extends {ol.filter.Filter}
  * @param {ol.geom.GeometryType} type The geometry type.
diff --git a/src/ol/filter/logicalfilter.js b/src/ol/filter/logicalfilter.js
index 72a9b5a58d..4eb8acebc5 100644
--- a/src/ol/filter/logicalfilter.js
+++ b/src/ol/filter/logicalfilter.js
@@ -10,9 +10,19 @@ goog.require('ol.filter.Filter');
 
 
 /**
+ * A filter to group (a) subfilter(s) by a logical operator (AND/OR/NOT).
+ *
+ * Example:
+ *
+ *     var f1 = new ol.filter.Filter(myFunc1);
+ *     var f2 = new ol.filter.Filter(myFunc2);
+ *     // match one of the two filters above
+ *     var logical = new ol.filter.Logical([f1, f2],
+ *         ol.filter.LogicalOperator.OR);
+ *
  * @constructor
  * @extends {ol.filter.Filter}
- * @param {Array.<ol.filter.Filter>} filters Filters to and-combine.
+ * @param {Array.<ol.filter.Filter>} filters Filters to combine.
  * @param {ol.filter.LogicalOperator} operator Operator.
  */
 ol.filter.Logical = function(filters, operator) {
@@ -61,6 +71,7 @@ ol.filter.Logical.prototype.applies = function(feature) {
       break;
     default:
       goog.asserts.assert(false, 'Unsupported operation: ' + this.operator);
+      break;
   }
   return !!result;
 };
diff --git a/src/ol/geolocation.js b/src/ol/geolocation.js
index 4e3f1a3a23..2d9ba70fab 100644
--- a/src/ol/geolocation.js
+++ b/src/ol/geolocation.js
@@ -31,6 +31,19 @@ ol.GeolocationProperty = {
 
 
 /**
+ * Helper class for providing HTML5 Geolocation capabilities.
+ * HTML5 Geolocation is used to locate a user's position.
+ *
+ * Example:
+ *
+ *     var geolocation = new ol.Geolocation();
+ *     // take the projection to use from the map's view
+ *     geolocation.bindTo('projection', map.getView());
+ *     // listen to changes in position
+ *     geolocation.on('change:position', function(evt) {
+ *       window.console.log(geolocation.getPosition());
+ *     });
+ *
  * @constructor
  * @extends {ol.Object}
  * @param {ol.GeolocationOptions=} opt_options Options.
@@ -126,7 +139,7 @@ ol.Geolocation.prototype.handleTrackingChanged_ = function() {
 
 
 /**
- * Is supported.
+ * Is HTML5 geolocation supported in the current browser?
  * @const
  * @type {boolean}
  */
@@ -170,8 +183,8 @@ ol.Geolocation.prototype.positionError_ = function(error) {
 
 
 /**
- * The accuracy of the position in meters.
- * @return {number|undefined} accuracy.
+ * Get the accuracy of the position in meters.
+ * @return {number|undefined} accuracy in meters.
  */
 ol.Geolocation.prototype.getAccuracy = function() {
   return /** @type {number} */ (
@@ -184,7 +197,8 @@ goog.exportProperty(
 
 
 /**
- * @return {number|undefined} Altitude.
+ * Get the altitude associated with the position.
+ * @return {number|undefined} The altitude in meters above the mean sea level.
  */
 ol.Geolocation.prototype.getAltitude = function() {
   return /** @type {number|undefined} */ (
@@ -197,6 +211,7 @@ goog.exportProperty(
 
 
 /**
+ * Get the altitude accuracy of the position.
  * @return {number|undefined} Altitude accuracy.
  */
 ol.Geolocation.prototype.getAltitudeAccuracy = function() {
@@ -210,6 +225,7 @@ goog.exportProperty(
 
 
 /**
+ * Get the heading as degrees clockwise from North.
  * @return {number|undefined} Heading.
  */
 ol.Geolocation.prototype.getHeading = function() {
@@ -223,7 +239,7 @@ goog.exportProperty(
 
 
 /**
- * The position of the device.
+ * Get the position of the device.
  * @return {ol.Coordinate|undefined} position.
  */
 ol.Geolocation.prototype.getPosition = function() {
@@ -237,6 +253,7 @@ goog.exportProperty(
 
 
 /**
+ * Get the projection associated with the position.
  * @return {ol.Projection|undefined} projection.
  */
 ol.Geolocation.prototype.getProjection = function() {
@@ -250,6 +267,7 @@ goog.exportProperty(
 
 
 /**
+ * Get the speed in meters per second.
  * @return {number|undefined} Speed.
  */
 ol.Geolocation.prototype.getSpeed = function() {
@@ -263,6 +281,7 @@ goog.exportProperty(
 
 
 /**
+ * Are we tracking the user's position?
  * @return {boolean|undefined} tracking.
  */
 ol.Geolocation.prototype.getTracking = function() {
@@ -276,6 +295,7 @@ goog.exportProperty(
 
 
 /**
+ * Get the tracking options.
  * @return {GeolocationPositionOptions|undefined} Tracking options.
  */
 ol.Geolocation.prototype.getTrackingOptions = function() {
@@ -289,6 +309,7 @@ goog.exportProperty(
 
 
 /**
+ * Set the projection to use for transforming the coordinates.
  * @param {ol.Projection} projection Projection.
  */
 ol.Geolocation.prototype.setProjection = function(projection) {
@@ -301,6 +322,7 @@ goog.exportProperty(
 
 
 /**
+ * Enable/disable tracking.
  * @param {boolean} tracking Enable or disable tracking.
  */
 ol.Geolocation.prototype.setTracking = function(tracking) {
@@ -313,6 +335,7 @@ goog.exportProperty(
 
 
 /**
+ * Set the tracking options.
  * @param {GeolocationPositionOptions} options Tracking options.
  */
 ol.Geolocation.prototype.setTrackingOptions = function(options) {
diff --git a/src/ol/map.js b/src/ol/map.js
index 2f8966853f..5f0fa37b6e 100644
--- a/src/ol/map.js
+++ b/src/ol/map.js
@@ -335,6 +335,7 @@ goog.inherits(ol.Map, ol.Object);
 
 
 /**
+ * Adds the given layer to the top of this map.
  * @param {ol.layer.Layer} layer Layer.
  */
 ol.Map.prototype.addLayer = function(layer) {
@@ -345,6 +346,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.
  * @param {ol.PreRenderFunction} preRenderFunction Pre-render function.
  */
 ol.Map.prototype.addPreRenderFunction = function(preRenderFunction) {
@@ -354,6 +357,8 @@ 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.
  * @param {Array.<ol.PreRenderFunction>} preRenderFunctions
  *     Pre-render functions.
  */
@@ -393,6 +398,7 @@ ol.Map.prototype.freezeRendering = function() {
 
 
 /**
+ * Get the map's renderer.
  * @return {ol.renderer.Map} Renderer.
  */
 ol.Map.prototype.getRenderer = function() {
@@ -401,6 +407,7 @@ ol.Map.prototype.getRenderer = function() {
 
 
 /**
+ * Get the element in which this map is rendered.
  * @return {Element|undefined} Target.
  */
 ol.Map.prototype.getTarget = function() {
@@ -454,6 +461,8 @@ ol.Map.prototype.getFeatures = function(options) {
 
 
 /**
+ * Gets the collection on interactions associated with this map.
+ * Interactions are used for e.g. pan, zoom and rotate.
  * @return {ol.Collection} Interactions.
  */
 ol.Map.prototype.getInteractions = function() {
@@ -462,6 +471,7 @@ ol.Map.prototype.getInteractions = function() {
 
 
 /**
+ * Get the collection of layers associated with this map.
  * @return {ol.Collection} Layers.
  */
 ol.Map.prototype.getLayers = function() {
@@ -489,6 +499,7 @@ ol.Map.prototype.getPixelFromCoordinate = function(coordinate) {
 
 
 /**
+ * Get the size of this map.
  * @return {ol.Size|undefined} Size.
  */
 ol.Map.prototype.getSize = function() {
@@ -501,6 +512,8 @@ goog.exportProperty(
 
 
 /**
+ * Get the view associated with this map. This can be a 2D or 3D view. A 2D
+ * view manages properties such as center and resolution.
  * @return {ol.View} View.
  */
 ol.Map.prototype.getView = function() {
@@ -785,6 +798,7 @@ ol.Map.prototype.requestRenderFrame = function() {
 
 
 /**
+ * Removes the given layer from the map.
  * @param {ol.layer.Layer} layer Layer.
  * @return {ol.layer.Layer|undefined} The removed layer or undefined if the
  *     layer was not found.
@@ -887,6 +901,7 @@ ol.Map.prototype.renderFrame_ = function(time) {
 
 
 /**
+ * Sets the whole collection of layers for this map.
  * @param {ol.Collection} layers Layers.
  */
 ol.Map.prototype.setLayers = function(layers) {
@@ -899,6 +914,7 @@ goog.exportProperty(
 
 
 /**
+ * Set the size of this map.
  * @param {ol.Size|undefined} size Size.
  */
 ol.Map.prototype.setSize = function(size) {
@@ -911,6 +927,7 @@ goog.exportProperty(
 
 
 /**
+ * Set the target element to render this map into.
  * @param {Element|string|undefined} target Target.
  */
 ol.Map.prototype.setTarget = function(target) {
@@ -926,6 +943,7 @@ goog.exportProperty(
 
 
 /**
+ * Set the view for this map.
  * @param {ol.IView} view View.
  */
 ol.Map.prototype.setView = function(view) {
diff --git a/src/ol/object.js b/src/ol/object.js
index fb6e1faaf7..a29683fd96 100644
--- a/src/ol/object.js
+++ b/src/ol/object.js
@@ -33,6 +33,7 @@ ol.ObjectProperty = {
 
 
 /**
+ * Base class implementing KVO (Key Value Observing).
  * @constructor
  * @extends {goog.events.EventTarget}
  * @param {Object.<string, *>=} opt_values Values.
@@ -137,6 +138,7 @@ ol.Object.getSetterName = function(key) {
 
 
 /**
+ * Binds a View to a Model.
  * @param {string} key Key.
  * @param {ol.Object} target Target.
  * @param {string=} opt_targetKey Target key.
@@ -161,6 +163,7 @@ ol.Object.prototype.bindTo =
 
 
 /**
+ * Gets a value.
  * @param {string} key Key.
  * @return {*} Value.
  */
@@ -197,6 +200,9 @@ ol.Object.prototype.getKeys = function() {
 
 
 /**
+ * Notify all observers of a change on this property. This notifies both
+ * objects that are bound to the object's property as well as the object
+ * that it is bound to.
  * @param {string} key Key.
  */
 ol.Object.prototype.notify = function(key) {
@@ -224,6 +230,7 @@ ol.Object.prototype.notifyInternal_ = function(key) {
 
 
 /**
+ * Listen for a certain type of event.
  * @param {string|Array.<string>} type The event type or array of event types.
  * @param {Function} listener The listener function.
  * @param {Object=} opt_scope Object is whose scope to call
@@ -236,6 +243,7 @@ ol.Object.prototype.on = function(type, listener, opt_scope) {
 
 
 /**
+ * Listen once for a certain type of event.
  * @param {string|Array.<string>} type The event type or array of event types.
  * @param {Function} listener The listener function.
  * @param {Object=} opt_scope Object is whose scope to call
@@ -248,6 +256,7 @@ ol.Object.prototype.once = function(type, listener, opt_scope) {
 
 
 /**
+ * Sets a value.
  * @param {string} key Key.
  * @param {*} value Value.
  */
@@ -271,6 +280,7 @@ ol.Object.prototype.set = function(key, value) {
 
 
 /**
+ * Sets a collection of key-value pairs.
  * @param {Object.<string, *>} options Options.
  */
 ol.Object.prototype.setOptions = function(options) {
@@ -288,12 +298,15 @@ ol.Object.prototype.setOptions = function(options) {
 
 
 /**
+ * Sets a collection of key-value pairs.
  * @param {Object.<string, *>} values Values.
  */
 ol.Object.prototype.setValues = ol.Object.prototype.setOptions;
 
 
 /**
+ * Removes a binding. Unbinding will set the unbound property to the current
+ *     value. The object will not be notified, as the value has not changed.
  * @param {string} key Key.
  */
 ol.Object.prototype.unbind = function(key) {
@@ -311,6 +324,7 @@ ol.Object.prototype.unbind = function(key) {
 
 
 /**
+ * Unlisten for a certain type of event.
  * @param {string|Array.<string>} type The event type or array of event types.
  * @param {Function} listener The listener function.
  * @param {Object=} opt_scope Object is whose scope to call
@@ -322,6 +336,8 @@ ol.Object.prototype.un = function(type, listener, opt_scope) {
 
 
 /**
+ * Removes an event listener which was added with listen() by the key returned
+ *     by on().
  * @param {?number} key Key.
  */
 ol.Object.prototype.unByKey = function(key) {
diff --git a/src/ol/overlay.js b/src/ol/overlay.js
index 74f4e44c1e..d3a955f4f2 100644
--- a/src/ol/overlay.js
+++ b/src/ol/overlay.js
@@ -37,6 +37,16 @@ ol.OverlayPositioning = {
 
 
 /**
+ * An element to show on top of the map, such as for a popup.
+ *
+ * Example:
+ *
+ *     var popup = new ol.Overlay({
+ *       map: map,
+ *       element: document.getElementById('popup')
+ *     });
+ *     popup.setPosition(coordinate);
+ *
  * @constructor
  * @extends {ol.Object}
  * @param {ol.OverlayOptions} options Overlay options.
@@ -103,6 +113,7 @@ goog.inherits(ol.Overlay, ol.Object);
 
 
 /**
+ * Get the DOM element of this overlay.
  * @return {Element|undefined} Element.
  */
 ol.Overlay.prototype.getElement = function() {
@@ -116,6 +127,7 @@ goog.exportProperty(
 
 
 /**
+ * Get the map associated with this overlay.
  * @return {ol.Map|undefined} Map.
  */
 ol.Overlay.prototype.getMap = function() {
@@ -129,6 +141,7 @@ goog.exportProperty(
 
 
 /**
+ * Get the current position of this overlay.
  * @return {ol.Coordinate|undefined} Position.
  */
 ol.Overlay.prototype.getPosition = function() {
@@ -142,6 +155,7 @@ goog.exportProperty(
 
 
 /**
+ * Get the current positioning of this overlay.
  * @return {ol.OverlayPositioning|undefined} Positioning.
  */
 ol.Overlay.prototype.getPositioning = function() {
@@ -211,6 +225,7 @@ ol.Overlay.prototype.handlePositioningChanged = function() {
 
 
 /**
+ * Set the DOM element to be associated with this overlay.
  * @param {Element|undefined} element Element.
  */
 ol.Overlay.prototype.setElement = function(element) {
@@ -223,6 +238,7 @@ goog.exportProperty(
 
 
 /**
+ * Set the map to be associated with this overlay.
  * @param {ol.Map|undefined} map Map.
  */
 ol.Overlay.prototype.setMap = function(map) {
@@ -235,6 +251,7 @@ goog.exportProperty(
 
 
 /**
+ * Set the position for this overlay.
  * @param {ol.Coordinate|undefined} position Position.
  */
 ol.Overlay.prototype.setPosition = function(position) {
diff --git a/src/ol/proj/proj.js b/src/ol/proj/proj.js
index c35453a2f9..4987185dad 100644
--- a/src/ol/proj/proj.js
+++ b/src/ol/proj/proj.js
@@ -100,6 +100,7 @@ ol.Projection = function(options) {
 
 
 /**
+ * Get the code for this projection, e.g. 'EPSG:4326'.
  * @return {string} Code.
  */
 ol.Projection.prototype.getCode = function() {
@@ -108,6 +109,7 @@ ol.Projection.prototype.getCode = function() {
 
 
 /**
+ * Get the validity extent for this projection.
  * @return {ol.Extent} Extent.
  */
 ol.Projection.prototype.getExtent = function() {
@@ -116,6 +118,11 @@ ol.Projection.prototype.getExtent = function() {
 
 
 /**
+ * Get the resolution of the point in degrees. For projections with degrees as
+ * the unit this will simply return the provided resolution. For other
+ * projections the point resolution is estimated by transforming the center
+ * pixel to EPSG:4326, measuring its width and height on the normal sphere,
+ * and taking the average of the width and height.
  * @param {number} resolution Resolution.
  * @param {ol.Coordinate} point Point.
  * @return {number} Point resolution.
@@ -124,6 +131,7 @@ ol.Projection.prototype.getPointResolution = goog.abstractMethod;
 
 
 /**
+ * Get the units of this projection.
  * @return {ol.ProjectionUnits} Units.
  */
 ol.Projection.prototype.getUnits = function() {
@@ -132,6 +140,7 @@ ol.Projection.prototype.getUnits = function() {
 
 
 /**
+ * Get the amount of meters per unit of this projection.
  * @return {number} Meters.
  */
 ol.Projection.prototype.getMetersPerUnit = function() {
@@ -140,6 +149,13 @@ ol.Projection.prototype.getMetersPerUnit = function() {
 
 
 /**
+ * Get the axis orientation of this projection.
+ * Example values are:
+ * enu - the default easting, northing, elevation.
+ * neu - northing, easting, up - useful for "lat/long" geographic coordinates,
+ *     or south orientated transverse mercator.
+ * wnu - westing, northing, up - some planetary coordinate systems have
+ *     "west positive" coordinate systems
  * @return {string} Axis orientation.
  */
 ol.Projection.prototype.getAxisOrientation = function() {
@@ -148,6 +164,7 @@ ol.Projection.prototype.getAxisOrientation = function() {
 
 
 /**
+ * Is this projection a global projection which spans the whole world?
  * @return {boolean} Wether the projection is global.
  */
 ol.Projection.prototype.isGlobal = function() {
diff --git a/src/ol/view2d.js b/src/ol/view2d.js
index 2c8e8bdee9..5a52c18931 100644
--- a/src/ol/view2d.js
+++ b/src/ol/view2d.js
@@ -31,6 +31,14 @@ ol.View2DProperty = {
 
 
 /**
+ * Create a new View2D, a View2D manages properties such as center,
+ *     projection, resolution and rotation.
+ *
+ * Example:
+ *
+ *     // to get the current extent
+ *     map.getView().getView2D().calculateExtent(map.getSize())
+ *
  * @constructor
  * @implements {ol.IView2D}
  * @implements {ol.IView3D}
@@ -128,6 +136,7 @@ ol.View2D.prototype.calculateCenterZoom = function(resolution, anchor) {
 
 
 /**
+ * Get the constrained the resolution of this view.
  * @param {number|undefined} resolution Resolution.
  * @param {number=} opt_delta Delta.
  * @param {number=} opt_direction Direction.
@@ -142,6 +151,7 @@ ol.View2D.prototype.constrainResolution = function(
 
 
 /**
+ * Get the constrained rotation of this view.
  * @param {number|undefined} rotation Rotation.
  * @param {number=} opt_delta Delta.
  * @return {number|undefined} Constrained rotation.
@@ -166,7 +176,7 @@ goog.exportProperty(
 
 
 /**
- * Calculate the extent for the given size in pixels, the current
+ * Calculate the extent for the given size in pixels, based on the current
  * resolution and the current center.
  * @param {ol.Size} size Box pixel size.
  * @return {ol.Extent} Extent.
@@ -247,6 +257,7 @@ ol.View2D.prototype.getResolutionForValueFunction = function(opt_power) {
 
 
 /**
+ * Get the current rotation of this view.
  * @return {number} Map rotation.
  */
 ol.View2D.prototype.getRotation = function() {
@@ -318,6 +329,7 @@ ol.View2D.prototype.getView3D = function() {
 
 
 /**
+ * Fit the given extent based on the given map size.
  * @param {ol.Extent} extent Extent.
  * @param {ol.Size} size Box pixel size.
  */
@@ -339,6 +351,7 @@ ol.View2D.prototype.isDef = function() {
 
 
 /**
+ * Set the center of the current view.
  * @param {ol.Coordinate|undefined} center Center.
  */
 ol.View2D.prototype.setCenter = function(center) {
@@ -351,6 +364,7 @@ goog.exportProperty(
 
 
 /**
+ * Set the projection of this view.
  * @param {ol.Projection|undefined} projection Projection.
  */
 ol.View2D.prototype.setProjection = function(projection) {
@@ -363,6 +377,7 @@ goog.exportProperty(
 
 
 /**
+ * Set the resolution for this view.
  * @param {number|undefined} resolution Resolution.
  */
 ol.View2D.prototype.setResolution = function(resolution) {
@@ -375,6 +390,7 @@ goog.exportProperty(
 
 
 /**
+ * Set the rotation for this view.
  * @param {number|undefined} rotation Rotation.
  */
 ol.View2D.prototype.setRotation = function(rotation) {

From 023767571151bb95c6e1cf883f1c993f3e4c692b Mon Sep 17 00:00:00 2001
From: Bart van den Eijnden <bartvde@opengeo.org>
Date: Wed, 12 Jun 2013 20:03:57 +0200
Subject: [PATCH 2/2] address review comments

---
 src/ol/filter/logicalfilter.js | 1 -
 src/ol/geolocation.js          | 2 +-
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/ol/filter/logicalfilter.js b/src/ol/filter/logicalfilter.js
index 4eb8acebc5..1e97edad1e 100644
--- a/src/ol/filter/logicalfilter.js
+++ b/src/ol/filter/logicalfilter.js
@@ -71,7 +71,6 @@ ol.filter.Logical.prototype.applies = function(feature) {
       break;
     default:
       goog.asserts.assert(false, 'Unsupported operation: ' + this.operator);
-      break;
   }
   return !!result;
 };
diff --git a/src/ol/geolocation.js b/src/ol/geolocation.js
index 2d9ba70fab..abd464d468 100644
--- a/src/ol/geolocation.js
+++ b/src/ol/geolocation.js
@@ -225,7 +225,7 @@ goog.exportProperty(
 
 
 /**
- * Get the heading as degrees clockwise from North.
+ * Get the heading as radians clockwise from North.
  * @return {number|undefined} Heading.
  */
 ol.Geolocation.prototype.getHeading = function() {