Add missing event documentation and stability tags

apidoc/plugins/exports.js

@@ -1,7 +1,9 @@
 /*
- * This plugin parses goog.exportSymbol and goog.exportProperty calls to build
+ * This plugin parses externs/oli.js as well as goog.exportSymbol and
- * a list of API symbols and properties. Everything else is marked undocumented,
+ * goog.exportProperty calls to build a list of API symbols and properties.
- * which will remove it from the docs.
+ * 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 = [];

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,8 +156,9 @@ ol.MapProperty = {
  * @constructor
  * @extends {ol.Object}
  * @param {olx.MapOptions} options Map options.
- * @fires {@link ol.MapEvent} ol.MapEvent
  * @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.
@@ -165,7 +166,7 @@ ol.MapProperty = {
  * @todo observable target {string|Element} the Element or id of the Element
  *       that the map is rendered in.
  * @todo observable view {ol.IView} the view that controls this map
-† */
+ */
 ol.Map = function(options) {
 
   goog.base(this);

src/ol/mapevent.js

@@ -11,11 +11,13 @@ 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,7 +109,7 @@ ol.ObjectAccessor.prototype.transform = function(from, to) {
  * @constructor
  * @extends {ol.Observable}
  * @param {Object.<string, *>=} opt_values Values.
- * @fires ol.ObjectEvent
+ * @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;