Improve and standardise event docs

src/ol/collection.js

@@ -33,6 +33,10 @@ ol.CollectionEventType = {
 
 
 /**
+ * @classdesc
+ * Events emitted by {@link ol.Collection} instances are instances of this
+ * type.
+ *
  * @constructor
  * @extends {goog.events.Event}
  * @implements {oli.CollectionEvent}

src/ol/events/condition.jsdoc

@@ -1,4 +1,15 @@
 /**
+ * Applications do not normally create event instances. They register (and
+ * unregister) event listener functions, which, when called by the library as
+ * the result of an event being dispatched, are passed event instances as their
+ * first argument. Listeners can be registered and unregistered on all objects
+ * descending from {@link ol.Observable}. All event instances have a `target`
+ * property, which corresponds to the object on which the event was dispatched.
+ * By default, `this` within the listener also refers to the target, though
+ * this can be configured in the listener registration function.
+ * Some classes have their own event type, which return additional
+ * properties; see the specific event class page for details.
+ *
  * @namespace ol.events
  */
 

src/ol/interaction/draganddropinteraction.js

@@ -192,6 +192,10 @@ ol.interaction.DragAndDropEventType = {
 
 
 /**
+ * @classdesc
+ * Events emitted by {@link ol.interaction.DragAndDrop} instances are instances
+ * of this type.
+ *
  * @constructor
  * @extends {goog.events.Event}
  * @implements {oli.interaction.DragAndDropEvent}

src/ol/interaction/dragboxinteraction.js

@@ -43,7 +43,8 @@ ol.DragBoxEventType = {
 
 /**
  * @classdesc
- * Object representing a dragbox event.
+ * Events emitted by {@link ol.interaction.DragBox} instances are instances of
+ * this type.
  *
  * @param {string} type The event type.
  * @param {ol.Coordinate} coordinate The event coordinate.

src/ol/interaction/drawinteraction.js

@@ -44,6 +44,10 @@ ol.DrawEventType = {
 
 
 /**
+ * @classdesc
+ * Events emitted by {@link ol.interaction.Draw} instances are instances of
+ * this type.
+ *
  * @constructor
  * @extends {goog.events.Event}
  * @implements {oli.DrawEvent}

src/ol/mapbrowserevent.js

@@ -20,6 +20,10 @@ goog.require('ol.pointer.PointerEventHandler');
 
 
 /**
+ * @classdesc
+ * Events emitted as map browser events are instances of this type.
+ * See {@link ol.Map} for which events trigger a map browser event.
+ *
  * @constructor
  * @extends {ol.MapEvent}
  * @implements {oli.MapBrowserEvent}

src/ol/mapevent.js

@@ -25,6 +25,10 @@ ol.MapEventType = {
 
 
 /**
+ * @classdesc
+ * Events emitted as map events are instances of this type.
+ * See {@link ol.Map} for which events trigger a map event.
+ *
  * @constructor
  * @extends {goog.events.Event}
  * @implements {oli.MapEvent}

src/ol/object.js

@@ -36,7 +36,8 @@ ol.ObjectEventType = {
 
 
 /**
- * Object representing a property change event.
+ * @classdesc
+ * Events emitted by {@link ol.Object} instances are instances of this type.
  *
  * @param {string} type The event type.
  * @param {string} key The property name.

src/ol/observable.js

@@ -84,7 +84,8 @@ ol.Observable.prototype.once = function(type, listener, opt_this) {
  * 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_this The object to use as `this` in `listener`.
+ * @param {Object=} opt_this The object which was used as `this` by the
+ * `listener`.
  * @api
  */
 ol.Observable.prototype.un = function(type, listener, opt_this) {

src/ol/source/vectorsource.js

@@ -483,6 +483,10 @@ ol.source.Vector.prototype.removeFromIdIndex_ = function(feature) {
 
 
 /**
+ * @classdesc
+ * Events emitted by {@link ol.source.Vector} instances are instances of this
+ * type.
+ *
  * @constructor
  * @extends {goog.events.Event}
  * @implements {oli.source.VectorEvent}