From 3595c2cce74293226c13ba39a563008d0f7fe5aa Mon Sep 17 00:00:00 2001
From: Andreas Hocevar <andreas.hocevar@gmail.com>
Date: Sat, 18 Jul 2015 15:27:16 +0200
Subject: [PATCH] Document change events properly

With this change, the generic 'change' event is properly documented, as
all other events. It is no longer necessary to annotate `@fires change` for
every ol.Observable subclass.
---
 config/jsdoc/api/template/tmpl/method.tmpl | 18 +++++++++---------
 src/ol/deviceorientation.js                |  4 +++-
 src/ol/geolocation.js                      |  4 +++-
 src/ol/geom/geometry.js                    |  4 +++-
 src/ol/layer/layer.js                      |  3 ++-
 src/ol/layer/layergroup.js                 |  3 ++-
 src/ol/observable.js                       |  9 ++++++++-
 src/ol/source/source.js                    |  3 ++-
 8 files changed, 32 insertions(+), 16 deletions(-)

diff --git a/config/jsdoc/api/template/tmpl/method.tmpl b/config/jsdoc/api/template/tmpl/method.tmpl
index 6f5d4c6e0c..d7b07bed34 100644
--- a/config/jsdoc/api/template/tmpl/method.tmpl
+++ b/config/jsdoc/api/template/tmpl/method.tmpl
@@ -24,7 +24,7 @@ var self = this;
     <?js } ?>
 </dt>
 <dd class="<?js= (data.stability && data.stability !== 'stable') ? 'unstable' : '' ?>">
-    
+
     <?js if (data.description) { ?>
     <div class="description">
         <?js= data.description ?>
@@ -39,20 +39,20 @@ var self = this;
             </li>
         </ul>
     <?js } ?>
-    
+
     <?js if (data['this']) { ?>
         <h5>This:</h5>
         <ul><li><?js= this.linkto(data['this'], data['this']) ?></li></ul>
     <?js } ?>
-    
+
     <?js if (data.stability || kind !== 'class') { ?>
     <?js if (data.params && params.length) { ?>
         <?js= this.partial('params.tmpl', params) ?>
     <?js } ?>
     <?js } ?>
-    
+
     <?js= this.partial('details.tmpl', data) ?>
-    
+
     <?js if (data.fires && fires.length) { ?>
     <h5>Fires:</h5>
     <ul><?js fires.forEach(function(f) {
@@ -68,7 +68,7 @@ var self = this;
             }
         ?>
         <li class="<?js= (eventDoclet || data).stability !== 'stable' ? 'unstable' : '' ?>">
-            <code><?js= self.linkto(f, type) ?></code>
+            <code><?js= eventClassName ? self.linkto(f, type) : type ?></code>
             <?js if (eventClassName) {
               var eventClass = self.find({longname: eventClassName})[0];
               if (eventClass) { ?>
@@ -96,7 +96,7 @@ var self = this;
         <li><?js= self.linkto(f) ?></li>
     <?js }); ?></ul>
     <?js } ?>
-    
+
     <?js if (data.exceptions && exceptions.length) { ?>
     <h5>Throws:</h5>
     <?js if (exceptions.length > 1) { ?><ul><?js
@@ -108,12 +108,12 @@ var self = this;
             <?js= self.partial('exceptions.tmpl', r) ?>
         <?js });
     } } ?>
-    
+
     <?js if (data.returns && returns.length) { ?>
     <?js if (returns.length > 1) { ?><h5>Returns:</h5><?js } ?>
     <?js= self.partial('returns.tmpl', data.returns) ?>
     <?js } ?>
-    
+
     <?js if (data.examples && examples.length) { ?>
         <h5>Example<?js= examples.length > 1? 's':'' ?></h5>
         <?js= this.partial('examples.tmpl', examples) ?>
diff --git a/src/ol/deviceorientation.js b/src/ol/deviceorientation.js
index 35b9a3b6fe..2933d89a83 100644
--- a/src/ol/deviceorientation.js
+++ b/src/ol/deviceorientation.js
@@ -67,9 +67,11 @@ ol.DeviceOrientationProperty = {
  *
  * @see http://www.w3.org/TR/orientation-event/
  *
+ * To get notified of device orientation changes, register a listener for the
+ * generic `change` event on your `ol.DeviceOrientation` instance.
+ *
  * @constructor
  * @extends {ol.Object}
- * @fires change Triggered when the device orientation changes.
  * @param {olx.DeviceOrientationOptions=} opt_options Options.
  * @api
  */
diff --git a/src/ol/geolocation.js b/src/ol/geolocation.js
index 62dc0f67ea..4386784b42 100644
--- a/src/ol/geolocation.js
+++ b/src/ol/geolocation.js
@@ -39,6 +39,9 @@ ol.GeolocationProperty = {
  * The [Geolocation API](http://www.w3.org/TR/geolocation-API/)
  * is used to locate a user's position.
  *
+ * To get notified of position changes, register a listener for the generic
+ * `change` event on your instance of `ol.Geolocation`.
+ *
  * Example:
  *
  *     var geolocation = new ol.Geolocation({
@@ -52,7 +55,6 @@ ol.GeolocationProperty = {
  *
  * @constructor
  * @extends {ol.Object}
- * @fires change Triggered when the position changes.
  * @param {olx.GeolocationOptions=} opt_options Options.
  * @api stable
  */
diff --git a/src/ol/geom/geometry.js b/src/ol/geom/geometry.js
index 5e2d1c5cf9..0a15563150 100644
--- a/src/ol/geom/geometry.js
+++ b/src/ol/geom/geometry.js
@@ -50,9 +50,11 @@ ol.geom.GeometryLayout = {
  * instantiated in apps.
  * Base class for vector geometries.
  *
+ * To get notified of changes to the geometry, register a listener for the
+ * generic `change` event on your geometry instance.
+ *
  * @constructor
  * @extends {ol.Object}
- * @fires change Triggered when the geometry changes.
  * @api stable
  */
 ol.geom.Geometry = function() {
diff --git a/src/ol/layer/layer.js b/src/ol/layer/layer.js
index 69346460a5..2690dc4fa0 100644
--- a/src/ol/layer/layer.js
+++ b/src/ol/layer/layer.js
@@ -19,10 +19,11 @@ goog.require('ol.source.State');
  * Layers group together those properties that pertain to how the data is to be
  * displayed, irrespective of the source of that data.
  *
+ * A generic `change` event is fired when the state of the source changes.
+ *
  * @constructor
  * @extends {ol.layer.Base}
  * @fires ol.render.Event
- * @fires change Triggered when the state of the source changes.
  * @param {olx.layer.LayerOptions} options Layer options.
  * @api stable
  */
diff --git a/src/ol/layer/layergroup.js b/src/ol/layer/layergroup.js
index 5233543c52..ece8ffa558 100644
--- a/src/ol/layer/layergroup.js
+++ b/src/ol/layer/layergroup.js
@@ -29,9 +29,10 @@ ol.layer.GroupProperty = {
  * @classdesc
  * A {@link ol.Collection} of layers that are handled together.
  *
+ * A generic `change` event is triggered when the group/Collection changes.
+ *
  * @constructor
  * @extends {ol.layer.Base}
- * @fires change Triggered when the group/Collection changes.
  * @param {olx.layer.GroupOptions=} opt_options Layer options.
  * @api stable
  */
diff --git a/src/ol/observable.js b/src/ol/observable.js
index a271ccde6a..0a1d55f8c3 100644
--- a/src/ol/observable.js
+++ b/src/ol/observable.js
@@ -16,6 +16,7 @@ goog.require('goog.events.EventType');
  *
  * @constructor
  * @extends {goog.events.EventTarget}
+ * @fires change
  * @suppress {checkStructDictInheritance}
  * @struct
  * @api stable
@@ -46,7 +47,6 @@ ol.Observable.unByKey = function(key) {
 
 /**
  * Increases the revision counter and dispatches a 'change' event.
- * @fires change
  * @api
  */
 ol.Observable.prototype.changed = function() {
@@ -55,6 +55,13 @@ ol.Observable.prototype.changed = function() {
 };
 
 
+/**
+ * Triggered when the revision counter is increased.
+ * @event change
+ * @api
+ */
+
+
 /**
  * @return {number} Revision.
  * @api
diff --git a/src/ol/source/source.js b/src/ol/source/source.js
index a6aeab177c..69a5d25019 100644
--- a/src/ol/source/source.js
+++ b/src/ol/source/source.js
@@ -37,9 +37,10 @@ ol.source.SourceOptions;
  * instantiated in apps.
  * Base class for {@link ol.layer.Layer} sources.
  *
+ * A generic `change` event is triggered when the state of the source changes.
+ *
  * @constructor
  * @extends {ol.Object}
- * @fires change Triggered when the state of the source changes.
  * @param {ol.source.SourceOptions} options Source options.
  * @api stable
  */