Merge pull request #3871 from ahocevar/change-event

Document change events properly

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) ?>

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
  */

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
  */

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() {

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
  */

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
  */

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

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
  */