Merge pull request #1898 from ahocevar/events

Document events

apidoc/plugins/exports.js

@@ -1,10 +1,13 @@
 /*
- * This plugin parses goog.exportSymbol and goog.exportProperty calls to build
- * a list of API symbols and properties. Everything else is marked undocumented,
- * which will remove it from the docs.
+ * This plugin parses externs/oli.js as well as goog.exportSymbol and
+ * goog.exportProperty calls to build a list of API symbols and properties.
+ * Unexported modules linked from @param or @fires will be marked unexported,
+ * and the documentation will not contain the constructor. Everything else is
+ * marked undocumented, which will remove it from the docs.
  */
 
 var api = [];
+var unexported = [];
 
 function collectExports(source) {
   var i, ii, symbol, property;
@@ -27,9 +30,23 @@ function collectExports(source) {
   }
 }
 
+function collectOliExports(source) {
+  var oli = source.match(/[^\{]oli\.([^;^ ]*);? ?/g);
+  if (oli) {
+    i = 0; ii = oli.length;
+    for (; i < ii; ++i) {
+      property = 'ol.' + oli[i].match(/oli.([^;]*)/)[1]
+          .replace('.prototype.', '#');
+      api.push(property);
+      unexported.push(property);
+    }
+  }
+}
+
 var encoding = env.conf.encoding || 'utf8';
 var fs = require('jsdoc/fs');
 collectExports(fs.readFileSync('build/src/external/src/exports.js', encoding));
+collectOliExports(fs.readFileSync('externs/oli.js', encoding));
 
 
 exports.handlers = {
@@ -56,7 +73,7 @@ exports.handlers = {
       }
     }
     if (api.indexOf(e.doclet.longname) > -1) {
-      // Add params of API symbols to the API
+      // Add params and events of API symbols to the API
       var names, name;
       var params = e.doclet.params;
       if (params) {
@@ -66,12 +83,23 @@ exports.handlers = {
             for (j = 0, jj=names.length; j < jj; ++j) {
               name = names[j];
               if (api.indexOf(name) === -1) {
-                api.push(name);
+                unexported.push(name);
               }
             }
           }
         }
       }
+      var fires = e.doclet.fires;
+      var event;
+      if (fires) {
+        for (i = 0, ii = fires.length; i < ii; ++i) {
+          event = fires[i].split(' ').pop();
+          name = event.replace('event:', '');
+          if (api.indexOf(name) === -1) {
+            unexported.push(name);
+          }
+        }
+      }
     }
   }
   
@@ -82,7 +110,8 @@ function filter(e) {
   if (e.doclet) {
     var fqn = e.doclet.longname;
     if (fqn) {
-      e.doclet.undocumented = (api.indexOf(fqn) === -1);
+      e.doclet.undocumented = (api.indexOf(fqn) === -1 && unexported.indexOf(fqn) === -1);
+      e.doclet.unexported = (unexported.indexOf(fqn) !== -1);
       // Remove parents that are not part of the API
       var parent;
       var parents = e.doclet.augments;

apidoc/plugins/inheritdoc.js

@@ -1,5 +1,5 @@
 /*
- * This is a hack to prevent inheritDoc and override tags from entirely removing
+ * This is a hack to prevent inheritDoc tags from entirely removing
  * documentation of the method that inherits the documentation.
  *
  * TODO: Remove this hack when https://github.com/jsdoc3/jsdoc/issues/53
@@ -8,7 +8,7 @@
 exports.nodeVisitor = {
 
   visitNode: function(node, e, parser, currentSourceName) {
-    if (/@(inheritDoc|override)(\n|\r)/.test(e.comment)) {
+    if (/@(inheritDoc)(\n|\r)/.test(e.comment)) {
       e.preventDefault = true;
     }
   }

apidoc/plugins/observable.js

@@ -21,6 +21,12 @@ exports.defineTags = function(dictionary) {
         description: description,
         readonly: readonly
       });
+      if (!doclet.fires) {
+        doclet.fires = [];
+      }
+      if (doclet.fires.indexOf('{@link ol.ObjectEvent} ol.event:ObjectEvent') === -1) {
+        doclet.fires.push('{@link ol.ObjectEvent} ol.event:ObjectEvent');
+      }
     }
   });
 };

apidoc/plugins/todo.js

@@ -22,6 +22,12 @@ exports.defineTags = function(dictionary) {
           description: description,
           readonly: readonly
         });
+        if (!doclet.fires) {
+          doclet.fires = [];
+        }
+        if (doclet.fires.indexOf('{@link ol.ObjectEvent} ol.event:ObjectEvent') === -1) {
+          doclet.fires.push('{@link ol.ObjectEvent} ol.event:ObjectEvent');
+        }
       }
     }
   });

apidoc/template/tmpl/container.tmpl

@@ -27,8 +27,7 @@
     <?js if (doc.kind === 'module' && doc.module) { ?>
         <?js= self.partial('method.tmpl', doc.module) ?>
     <?js } ?>
-    
-    <?js if (doc.kind === 'class') { ?>
+    <?js if (!doc.unexported && doc.kind === 'class') { ?>
         <?js= self.partial('method.tmpl', doc) ?>
     <?js } else { ?>
         <?js if (doc.description) { ?>
@@ -101,6 +100,18 @@
 
     <?js } ?>
 
+    <?js
+        var events = doc.events;
+        if (events && events.length && events.forEach) {
+    ?>
+        <h3 class="subsection-title">Events</h3>
+        <?js if (observables && observables.length) { ?>
+        <p>These events are available in addition to the <b>Observable Properties</b> events listed above.</p>
+        <?js } ?>
+        <dl><?js= self.partial('events.tmpl', events) ?></dl>
+
+    <?js } ?>
+
     <?js
         var members = self.find({kind: 'member', memberof: title === 'Globals'? {isUndefined: true} : doc.longname});
         if (members && members.length && members.forEach) { 

apidoc/template/tmpl/observables.tmpl

@@ -8,7 +8,7 @@
     <th>Name</th>
     <th>Type</th>
     <th>Settable</th>
-    <th>Event</th>
+    <th><a href="ol.ObjectEvent.html">ol.ObjectEvent</a> type</th>
     <th class="last">Description</th>
   </tr>
   </thead>

build.py

@@ -376,7 +376,7 @@ virtual('lint', 'build/lint-timestamp', 'build/lint-generated-timestamp',
 def build_lint_src_timestamp(t):
     t.run('%(GJSLINT)s',
           '--jslint_error=all',
-          '--custom_jsdoc_tags=todo,function',
+          '--custom_jsdoc_tags=event,fires,todo,function',
           '--strict',
           t.newer(t.dependencies))
     t.touch()

externs/oli.js

@@ -11,7 +11,7 @@ var oli;
 
 
 /** @interface */
-oli.CollectionEvent = function() {};
+oli.CollectionEvent;
 
 
 /** @type {*} */
@@ -170,7 +170,7 @@ oli.View2DState.prototype.rotation;
 /**
  * @interface
  */
-oli.control.Control = function() {};
+oli.control.Control;
 
 
 /**
@@ -182,7 +182,7 @@ oli.control.Control.prototype.setMap = function(map) {};
 
 
 /** @interface */
-oli.interaction.DragAndDropEvent = function() {};
+oli.interaction.DragAndDropEvent;
 
 
 /** @type {Array.<ol.Feature>} */
@@ -195,7 +195,7 @@ oli.interaction.DragAndDropEvent.prototype.projection;
 
 
 /** @interface */
-oli.render.Event = function() {};
+oli.render.Event;
 
 
 /** @type {CanvasRenderingContext2D|null|undefined} */

src/ol/collection.js

@@ -16,7 +16,17 @@ goog.require('ol.Object');
  * @enum {string}
  */
 ol.CollectionEventType = {
+  /**
+   * Triggered when an item is added to the collection.
+   * @event ol.CollectionEvent#add
+   * @todo stability experimental
+   */
   ADD: 'add',
+  /**
+   * Triggered when an item is removed from the collection.
+   * @event ol.CollectionEvent#remove
+   * @todo stability experimental
+   */
   REMOVE: 'remove'
 };
 
@@ -35,7 +45,9 @@ ol.CollectionEvent = function(type, opt_element, opt_target) {
   goog.base(this, type, opt_target);
 
   /**
+   * The element that is added to or removed from the collection.
    * @type {*}
+   * @todo stability experimental
    */
   this.element = opt_element;
 
@@ -56,6 +68,7 @@ ol.CollectionProperty = {
  * A mutable MVC Array.
  * @constructor
  * @extends {ol.Object}
+ * @fires {@link ol.CollectionEvent} ol.CollectionEvent
  * @param {Array=} opt_array Array.
  * @todo stability experimental
  * @todo observable length {number} readonly the length of the array

src/ol/interaction/draganddropinteraction.js

@@ -19,6 +19,8 @@ goog.require('ol.proj');
 /**
  * @constructor
  * @extends {ol.interaction.Interaction}
+ * @fires {@link ol.interaction.DragAndDropEvent}
+ *     ol.interaction.DragAndDropEvent
  * @param {olx.interaction.DragAndDropOptions=} opt_options Options.
  */
 ol.interaction.DragAndDrop = function(opt_options) {
@@ -175,6 +177,11 @@ ol.interaction.DragAndDrop.prototype.tryReadFeatures_ = function(format, text) {
  * @enum {string}
  */
 ol.interaction.DragAndDropEventType = {
+  /**
+   * Triggered when features are added
+   * @event ol.interaction.DragAndDropEvent#addfeatures
+   * @todo stability experimental
+   */
   ADD_FEATURES: 'addfeatures'
 };
 
@@ -196,11 +203,13 @@ ol.interaction.DragAndDropEvent =
 
   /**
    * @type {Array.<ol.Feature>|undefined}
+   * @todo stability experimental
    */
   this.features = opt_features;
 
   /**
    * @type {ol.proj.Projection|undefined}
+   * @todo stability experimental
    */
   this.projection = opt_projection;
 

src/ol/interaction/dragboxinteraction.js

@@ -31,7 +31,17 @@ ol.DRAG_BOX_HYSTERESIS_PIXELS_SQUARED =
  * @enum {string}
  */
 ol.DragBoxEventType = {
+  /**
+   * Triggered upon drag box start.
+   * @event ol.DragBoxEvent#boxstart
+   * @todo stability experimental
+   */
   BOXSTART: 'boxstart',
+  /**
+   * Triggered upon drag box end.
+   * @event ol.DragBoxEvent#boxstart
+   * @todo stability experimental
+   */
   BOXEND: 'boxend'
 };
 
@@ -70,6 +80,7 @@ goog.inherits(ol.DragBoxEvent, goog.events.Event);
  *
  * @constructor
  * @extends {ol.interaction.Pointer}
+ * @fires {@link ol.DragBoxEvent} ol.DragBoxEvent
  * @param {olx.interaction.DragBoxOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/interaction/drawinteraction.js

@@ -29,7 +29,17 @@ goog.require('ol.style.Style');
  * @enum {string}
  */
 ol.DrawEventType = {
+  /**
+   * Triggered upon feature draw start
+   * @event ol.DrawEvent#drawstart
+   * @todo stability experimental
+   */
   DRAWSTART: 'drawstart',
+  /**
+   * Triggered upon feature draw end
+   * @event ol.DrawEvent#drawend
+   * @todo stability experimental
+   */
   DRAWEND: 'drawend'
 };
 
@@ -47,7 +57,9 @@ ol.DrawEvent = function(type, feature) {
   goog.base(this, type);
 
   /**
+   * The feature being drawn.
    * @type {ol.Feature}
+   * @todo stability experimental
    */
   this.feature = feature;
 
@@ -60,6 +72,7 @@ goog.inherits(ol.DrawEvent, goog.events.Event);
  * Interaction that allows drawing geometries
  * @constructor
  * @extends {ol.interaction.Pointer}
+ * @fires {@link ol.DrawEvent} ol.DrawEvent
  * @param {olx.interaction.DrawOptions} options Options.
  * @todo stability experimental
  */

src/ol/layer/heatmaplayer.js

@@ -24,6 +24,7 @@ ol.layer.HeatmapLayerProperty = {
 /**
  * @constructor
  * @extends {ol.layer.Vector}
+ * @fires {@link ol.render.Event} ol.render.Event
  * @param {olx.layer.HeatmapOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/layer/imagelayer.js

@@ -7,6 +7,7 @@ goog.require('ol.layer.Layer');
 /**
  * @constructor
  * @extends {ol.layer.Layer}
+ * @fires {@link ol.render.Event} ol.render.Event
  * @param {olx.layer.LayerOptions} options Layer options.
  * @todo stability experimental
  */

src/ol/layer/layer.js

@@ -12,6 +12,7 @@ goog.require('ol.source.Source');
 /**
  * @constructor
  * @extends {ol.layer.Base}
+ * @fires {@link ol.render.Event} ol.render.Event
  * @param {olx.layer.LayerOptions} options Layer options.
  * @todo stability experimental
  * @todo observable brightness {number} the brightness of the layer

src/ol/layer/tilelayer.js

@@ -16,6 +16,7 @@ ol.layer.TileProperty = {
 /**
  * @constructor
  * @extends {ol.layer.Layer}
+ * @fires {@link ol.render.Event} ol.render.Event
  * @param {olx.layer.TileOptions} options Tile layer options.
  * @todo stability experimental
  * @todo observable preload {number} the level to preload tiles up to

src/ol/layer/vectorlayer.js

@@ -10,6 +10,7 @@ goog.require('ol.layer.Layer');
 /**
  * @constructor
  * @extends {ol.layer.Layer}
+ * @fires {@link ol.render.Event} ol.render.Event
  * @param {olx.layer.VectorOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/map.js

@@ -156,6 +156,9 @@ ol.MapProperty = {
  * @constructor
  * @extends {ol.Object}
  * @param {olx.MapOptions} options Map options.
+ * @fires {@link ol.MapBrowserEvent} ol.MapBrowserEvent
+ * @fires {@link ol.MapEvent} ol.MapEvent
+ * @fires {@link ol.render.Event} ol.render.Event
  * @todo stability experimental
  * @todo observable layergroup {ol.layer.LayerGroup} a layer group containing
  *       the layers in this map.
@@ -766,7 +769,8 @@ ol.Map.prototype.getViewport = function() {
 /**
  * @return {Element} The map's overlay container. Elements added to this
  * container will let mousedown and touchstart events through to the map, so
- * clicks and gestures on an overlay will trigger MapBrowserEvent events.
+ * clicks and gestures on an overlay will trigger {@link ol.MapBrowserEvent}
+ * events.
  */
 ol.Map.prototype.getOverlayContainer = function() {
   return this.overlayContainer_;
@@ -776,7 +780,8 @@ ol.Map.prototype.getOverlayContainer = function() {
 /**
  * @return {Element} The map's overlay container. Elements added to this
  * container won't let mousedown and touchstart events through to the map, so
- * clicks and gestures on an overlay don't trigger any MapBrowserEvent.
+ * clicks and gestures on an overlay don't trigger any
+ * {@link ol.MapBrowserEvent}.
  */
 ol.Map.prototype.getOverlayContainerStopEvent = function() {
   return this.overlayContainerStopEvent_;

src/ol/mapbrowserevent.js

@@ -41,16 +41,19 @@ ol.MapBrowserEvent = function(type, map, browserEvent, opt_frameState) {
   /**
    * @const
    * @type {Event}
+   * @todo stability experimental
    */
   this.originalEvent = browserEvent.getBrowserEvent();
 
   /**
    * @type {ol.Coordinate}
+   * @todo stability experimental
    */
   this.coordinate = map.getEventCoordinate(this.originalEvent);
 
   /**
    * @type {ol.Pixel}
+   * @todo stability experimental
    */
   this.pixel = map.getEventPixel(this.originalEvent);
 
@@ -460,11 +463,32 @@ ol.MapBrowserEventHandler.prototype.disposeInternal = function() {
  */
 ol.MapBrowserEvent.EventType = {
   // derived event types
+  /**
+   * A true single click with no dragging and no double click. Note that this
+   * event is delayed by 250 ms to ensure that it is not a double click.
+   * @event ol.MapBrowserEvent#singleclick
+   * @todo stability experimental
+   */
   SINGLECLICK: 'singleclick',
+  /**
+   * A true double click, with no dragging.
+   * @event ol.MapBrowserEvent#dblclick
+   * @todo stability experimental
+   */
   DBLCLICK: goog.events.EventType.DBLCLICK,
+  /**
+   * Triggered when a pointer is dragged.
+   * @event ol.MapBrowserEvent#pointerdrag
+   * @todo stability experimental
+   */
   POINTERDRAG: 'pointerdrag',
 
   // original pointer event types
+  /**
+   * Triggered when a pointer is moved.
+   * @event ol.MapBrowserEvent#pointermove
+   * @todo stability experimental
+   */
   POINTERMOVE: 'pointermove',
   POINTERDOWN: 'pointerdown',
   POINTERUP: 'pointerup',

src/ol/mapevent.js

@@ -8,7 +8,17 @@ goog.require('goog.events.Event');
  * @enum {string}
  */
 ol.MapEventType = {
+  /**
+   * Triggered after a map frame is rendered.
+   * @event ol.MapEvent#postrender
+   * @todo stability experimental
+   */
   POSTRENDER: 'postrender',
+  /**
+   * Triggered after the map is moved.
+   * @event ol.MapEvent#moveend
+   * @todo stability experimental
+   */
   MOVEEND: 'moveend'
 };
 

src/ol/object.js

@@ -20,7 +20,17 @@ goog.require('ol.Observable');
  * @enum {string}
  */
 ol.ObjectEventType = {
+  /**
+   * Triggered before a property is changed.
+   * @event ol.ObjectEvent#beforepropertychange
+   * @todo stability experimental
+   */
   BEFOREPROPERTYCHANGE: 'beforepropertychange',
+  /**
+   * Triggered when a property is changed.
+   * @event ol.ObjectEvent#propertychange
+   * @todo stability experimental
+   */
   PROPERTYCHANGE: 'propertychange'
 };
 
@@ -99,6 +109,7 @@ ol.ObjectAccessor.prototype.transform = function(from, to) {
  * @constructor
  * @extends {ol.Observable}
  * @param {Object.<string, *>=} opt_values Values.
+ * @fires {@link ol.ObjectEvent} ol.ObjectEvent
  * @todo stability experimental
  */
 ol.Object = function(opt_values) {

src/ol/observable.js

@@ -8,7 +8,8 @@ goog.require('goog.events.EventType');
 
 /**
  * An event target providing convenient methods for listener registration
- * and unregistration.
+ * and unregistration. A generic `change` event is always available through
+ * {@link ol.Observable#dispatchChangeEvent}.
  * @constructor
  * @extends {goog.events.EventTarget}
  * @suppress {checkStructDictInheritance}
@@ -30,6 +31,9 @@ goog.inherits(ol.Observable, goog.events.EventTarget);
 
 
 /**
+ * Dispatches a `change` event. Register a listener for this event to get
+ * notified of changes.
+ * @fires change
  * @todo stability experimental
  */
 ol.Observable.prototype.dispatchChangeEvent = function() {

src/ol/render/renderevent.js

@@ -9,8 +9,20 @@ goog.require('ol.render.IVectorContext');
  * @enum {string}
  */
 ol.render.EventType = {
+  /**
+   * @event ol.render.Event#postcompose
+   * @todo stability experimental
+   */
   POSTCOMPOSE: 'postcompose',
+  /**
+   * @event ol.render.Event#precompose
+   * @todo stability experimental
+   */
   PRECOMPOSE: 'precompose',
+  /**
+   * @event ol.render.Event#render
+   * @todo stability experimental
+   */
   RENDER: 'render'
 };
 
@@ -35,21 +47,29 @@ ol.render.Event = function(
 
   /**
    * @type {ol.render.IVectorContext|undefined}
+   * @todo stability experimental
    */
   this.vectorContext = opt_vectorContext;
 
   /**
    * @type {oli.FrameState|undefined}
+   * @todo stability experimental
    */
   this.frameState = opt_frameState;
 
   /**
+   * Canvas context. Only available when a Canvas renderer is used,
+   * null otherwise.
    * @type {CanvasRenderingContext2D|null|undefined}
+   * @todo stability experimental
    */
   this.context = opt_context;
 
   /**
+   * WebGL context. Only available when a WebGL renderer is used, null
+   * otherwise.
    * @type {ol.webgl.Context|null|undefined}
+   * @todo stability experimental
    */
   this.glContext = opt_glContext;
 

src/ol/source/geojsonsource.js

@@ -8,6 +8,7 @@ goog.require('ol.source.VectorFile');
 /**
  * @constructor
  * @extends {ol.source.VectorFile}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.GeoJSONOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/source/gpxsource.js

@@ -8,6 +8,7 @@ goog.require('ol.source.VectorFile');
 /**
  * @constructor
  * @extends {ol.source.VectorFile}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.GPXOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/source/igcsource.js

@@ -8,6 +8,7 @@ goog.require('ol.source.VectorFile');
 /**
  * @constructor
  * @extends {ol.source.VectorFile}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.IGCOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/source/kmlsource.js

@@ -8,6 +8,7 @@ goog.require('ol.source.VectorFile');
 /**
  * @constructor
  * @extends {ol.source.VectorFile}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.KMLOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/source/osmxmlsource.js

@@ -8,6 +8,7 @@ goog.require('ol.source.VectorFile');
 /**
  * @constructor
  * @extends {ol.source.VectorFile}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.OSMXMLOptions=} opt_options Options.
  */
 ol.source.OSMXML = function(opt_options) {

src/ol/source/topojsonsource.js

@@ -8,6 +8,7 @@ goog.require('ol.source.VectorFile');
 /**
  * @constructor
  * @extends {ol.source.VectorFile}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.TopoJSONOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/source/vectorfilesource.js

@@ -22,6 +22,7 @@ goog.require('ol.xml');
 /**
  * @constructor
  * @extends {ol.source.Vector}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.VectorFileOptions=} opt_options Options.
  * @todo stability experimental
  */

src/ol/source/vectorsource.js

@@ -21,7 +21,17 @@ goog.require('ol.structs.RBush');
  * @enum {string}
  */
 ol.source.VectorEventType = {
+  /**
+   * Triggered when a feature is added to the source.
+   * @event ol.source.VectorEvent#addfeature
+   * @todo stability experimental
+   */
   ADDFEATURE: 'addfeature',
+  /**
+   * Triggered when a feature is removed from the source.
+   * @event ol.source.VectorEvent#removefeature
+   * @todo stability experimental
+   */
   REMOVEFEATURE: 'removefeature'
 };
 
@@ -30,6 +40,7 @@ ol.source.VectorEventType = {
 /**
  * @constructor
  * @extends {ol.source.Source}
+ * @fires {@link ol.source.VectorEvent} ol.source.VectorEvent
  * @param {olx.source.VectorOptions=} opt_options Vector source options.
  * @todo stability experimental
  */
@@ -372,7 +383,9 @@ ol.source.VectorEvent = function(type, opt_feature) {
   goog.base(this, type);
 
   /**
+   * The feature being added or removed.
    * @type {ol.Feature|undefined}
+   * @todo stability experimental
    */
   this.feature = opt_feature;