Merge pull request #5010 from ahocevar/event-docs-externs

Add and fix API docs for ol.events.Event stack

externs/oli.js

@@ -9,6 +9,33 @@
 var oli;
 
 
+/**
+ * @interface
+ */
+oli.events.Event = function() {};
+
+
+/**
+ * @type {Object}
+ */
+oli.events.Event.prototype.target;
+
+
+/**
+ * @type {string}
+ */
+oli.events.Event.prototype.type;
+
+
+/**
+ */
+oli.events.Event.prototype.preventDefault = function() {};
+
+
+/**
+ */
+oli.events.Event.prototype.stopPropagation = function() {};
+
 
 /**
  * @interface
@@ -22,7 +49,6 @@ oli.CollectionEvent = function() {};
 oli.CollectionEvent.prototype.element;
 
 
-
 /**
  * @interface
  */
@@ -41,7 +67,6 @@ oli.DragBoxEvent.prototype.coordinate;
 oli.DragBoxEvent.prototype.mapBrowserEvent;
 
 
-
 /**
  * @interface
  */
@@ -54,7 +79,6 @@ oli.DrawEvent = function() {};
 oli.DrawEvent.prototype.feature;
 
 
-
 /**
  * @interface
  */
@@ -73,7 +97,6 @@ oli.ModifyEvent.prototype.features;
 oli.ModifyEvent.prototype.mapBrowserPointerEvent;
 
 
-
 /**
  * @interface
  */
@@ -92,7 +115,6 @@ oli.ObjectEvent.prototype.key;
 oli.ObjectEvent.prototype.oldValue;
 
 
-
 /**
  * @interface
  */
@@ -123,7 +145,6 @@ oli.MapBrowserEvent.prototype.pixel;
 oli.MapBrowserEvent.prototype.dragging;
 
 
-
 /**
  * @interface
  */
@@ -166,7 +187,6 @@ oli.SelectEvent.prototype.selected;
 oli.SelectEvent.prototype.mapBrowserEvent;
 
 
-
 /**
  * @type {Object}
  */
@@ -186,7 +206,6 @@ oli.control.Control = function() {};
 oli.control.Control.prototype.setMap = function(map) {};
 
 
-
 /**
  * @type {Object}
  */
@@ -217,7 +236,6 @@ oli.interaction.DragAndDropEvent.prototype.projection;
 oli.interaction.DragAndDropEvent.prototype.file;
 
 
-
 /**
  * @interface
  */
@@ -242,7 +260,6 @@ oli.interaction.TranslateEvent.prototype.coordinate;
 oli.render;
 
 
-
 /**
  * @interface
  */

src/ol/events.js

@@ -73,7 +73,13 @@ ol.events.EventTargetLike;
 /**
  * Key to use with {@link ol.Observable#unByKey}.
  *
- * @typedef {ol.events.ListenerObjType}
+ * @typedef {{bindTo: (Object|undefined),
+ *     boundListener: (ol.events.ListenerFunctionType|undefined),
+ *     callOnce: boolean,
+ *     deleteIndex: (number|undefined),
+ *     listener: ol.events.ListenerFunctionType,
+ *     target: (EventTarget|ol.events.EventTarget),
+ *     type: string}}
  * @api
  */
 ol.events.Key;
@@ -90,19 +96,7 @@ ol.events.ListenerFunctionType;
 
 
 /**
- * @typedef {{bindTo: (Object|undefined),
+ * @param {ol.events.Key} listenerObj Listener object.
- *     boundListener: (ol.events.ListenerFunctionType|undefined),
- *     callOnce: boolean,
- *     deleteIndex: (number|undefined),
- *     listener: ol.events.ListenerFunctionType,
- *     target: (EventTarget|ol.events.EventTarget),
- *     type: string}}
- */
-ol.events.ListenerObjType;
-
-
-/**
- * @param {ol.events.ListenerObjType} listenerObj Listener object.
  * @return {ol.events.ListenerFunctionType} Bound listener.
  */
 ol.events.bindListener_ = function(listenerObj) {
@@ -120,15 +114,15 @@ ol.events.bindListener_ = function(listenerObj) {
 
 
 /**
- * Finds the matching {@link ol.events.ListenerObjType} in the given listener
+ * Finds the matching {@link ol.events.Key} in the given listener
  * array.
  *
- * @param {!Array<!ol.events.ListenerObjType>} listeners Array of listeners.
+ * @param {!Array<!ol.events.Key>} listeners Array of listeners.
  * @param {!Function} listener The listener function.
  * @param {Object=} opt_this The `this` value inside the listener.
  * @param {boolean=} opt_setDeleteIndex Set the deleteIndex on the matching
  *     listener, for {@link ol.events.unlistenByKey}.
- * @return {ol.events.ListenerObjType|undefined} The matching listener object.
+ * @return {ol.events.Key|undefined} The matching listener object.
  * @private
  */
 ol.events.findListener_ = function(listeners, listener, opt_this,
@@ -151,7 +145,7 @@ ol.events.findListener_ = function(listeners, listener, opt_this,
 /**
  * @param {ol.events.EventTargetLike} target Target.
  * @param {string} type Type.
- * @return {Array.<ol.events.ListenerObjType>|undefined} Listeners.
+ * @return {Array.<ol.events.Key>|undefined} Listeners.
  */
 ol.events.getListeners = function(target, type) {
   var listenerMap = target[ol.events.LISTENER_MAP_PROP_];
@@ -163,7 +157,7 @@ ol.events.getListeners = function(target, type) {
  * Get the lookup of listeners.  If one does not exist on the target, it is
  * created.
  * @param {ol.events.EventTargetLike} target Target.
- * @return {!Object.<string, Array.<ol.events.ListenerObjType>>} Map of
+ * @return {!Object.<string, Array.<ol.events.Key>>} Map of
  *     listeners by event type.
  * @private
  */
@@ -232,7 +226,7 @@ ol.events.listen = function(target, type, listener, opt_this, opt_once) {
       listenerObj.callOnce = false;
     }
   } else {
-    listenerObj = /** @type {ol.events.ListenerObjType} */ ({
+    listenerObj = /** @type {ol.events.Key} */ ({
       bindTo: opt_this,
       callOnce: !!opt_once,
       listener: listener,

src/ol/events/event.js

@@ -12,6 +12,7 @@ goog.provide('ol.events.Event');
  * {@link ol.events.EventTarget}.
  *
  * @constructor
+ * @implements {oli.events.Event}
  * @param {string} type Type.
  * @param {Object=} opt_target Target.
  */
@@ -23,22 +24,34 @@ ol.events.Event = function(type, opt_target) {
   this.propagationStopped;
 
   /**
+   * The event type.
    * @type {string}
+   * @api stable
    */
   this.type = type;
 
   /**
-   * @type {Object|undefined}
+   * The event target.
+   * @type {Object}
+   * @api stable
    */
-  this.target = opt_target;
+  this.target = opt_target || null;
 
 };
 
 
 /**
- * Stop event propagation
+ * Stop event propagation.
+ * @function
+ * @api stable
  */
 ol.events.Event.prototype.preventDefault =
+
+/**
+ * Stop event propagation.
+ * @function
+ * @api stable
+ */
 ol.events.Event.prototype.stopPropagation = function() {
   this.propagationStopped = true;
 };