From 7a5a5d75e736ddb25b49d194d37629569938a33f Mon Sep 17 00:00:00 2001 From: Peter Robins Date: Sun, 27 Jul 2014 17:11:34 +0000 Subject: [PATCH] Improve and standardise event docs --- src/ol/collection.js | 4 ++++ src/ol/events/condition.jsdoc | 11 +++++++++++ src/ol/interaction/draganddropinteraction.js | 4 ++++ src/ol/interaction/dragboxinteraction.js | 3 ++- src/ol/interaction/drawinteraction.js | 4 ++++ src/ol/mapbrowserevent.js | 4 ++++ src/ol/mapevent.js | 4 ++++ src/ol/object.js | 3 ++- src/ol/observable.js | 3 ++- src/ol/source/vectorsource.js | 4 ++++ 10 files changed, 41 insertions(+), 3 deletions(-) diff --git a/src/ol/collection.js b/src/ol/collection.js index d4b9519542..2fe1a33357 100644 --- a/src/ol/collection.js +++ b/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} diff --git a/src/ol/events/condition.jsdoc b/src/ol/events/condition.jsdoc index 8fdd8d4845..e7cefa866e 100644 --- a/src/ol/events/condition.jsdoc +++ b/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 */ diff --git a/src/ol/interaction/draganddropinteraction.js b/src/ol/interaction/draganddropinteraction.js index 4f14755348..0e4f590ad3 100644 --- a/src/ol/interaction/draganddropinteraction.js +++ b/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} diff --git a/src/ol/interaction/dragboxinteraction.js b/src/ol/interaction/dragboxinteraction.js index 0bb34da53e..686351781d 100644 --- a/src/ol/interaction/dragboxinteraction.js +++ b/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. diff --git a/src/ol/interaction/drawinteraction.js b/src/ol/interaction/drawinteraction.js index efef4bb5a7..dbceece9c6 100644 --- a/src/ol/interaction/drawinteraction.js +++ b/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} diff --git a/src/ol/mapbrowserevent.js b/src/ol/mapbrowserevent.js index 0e1cf914bd..cbd625612f 100644 --- a/src/ol/mapbrowserevent.js +++ b/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} diff --git a/src/ol/mapevent.js b/src/ol/mapevent.js index 99b3646c73..f0744c5243 100644 --- a/src/ol/mapevent.js +++ b/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} diff --git a/src/ol/object.js b/src/ol/object.js index b6baf64fd4..9b44e6b71f 100644 --- a/src/ol/object.js +++ b/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. diff --git a/src/ol/observable.js b/src/ol/observable.js index aba4052d34..2d89b999c4 100644 --- a/src/ol/observable.js +++ b/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.} 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) { diff --git a/src/ol/source/vectorsource.js b/src/ol/source/vectorsource.js index 7353292b24..66ab6ad84f 100644 --- a/src/ol/source/vectorsource.js +++ b/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}