From a3b5376520ff5af50555167bd056d4d642d2ac0b Mon Sep 17 00:00:00 2001 From: ahocevar Date: Wed, 26 Mar 2014 14:04:58 +0100 Subject: [PATCH] Add missing event documentation and stability tags --- apidoc/plugins/exports.js | 8 +++++--- externs/oli.js | 8 ++++---- src/ol/collection.js | 13 +++++++++++++ src/ol/interaction/draganddropinteraction.js | 9 +++++++++ src/ol/interaction/dragboxinteraction.js | 11 +++++++++++ src/ol/interaction/drawinteraction.js | 13 +++++++++++++ src/ol/layer/heatmaplayer.js | 1 + src/ol/layer/imagelayer.js | 1 + src/ol/layer/layer.js | 1 + src/ol/layer/tilelayer.js | 1 + src/ol/layer/vectorlayer.js | 1 + src/ol/map.js | 5 +++-- src/ol/mapevent.js | 2 ++ src/ol/object.js | 12 +++++++++++- src/ol/observable.js | 6 +++++- src/ol/render/renderevent.js | 20 ++++++++++++++++++++ src/ol/source/geojsonsource.js | 1 + src/ol/source/gpxsource.js | 1 + src/ol/source/igcsource.js | 1 + src/ol/source/kmlsource.js | 1 + src/ol/source/osmxmlsource.js | 1 + src/ol/source/topojsonsource.js | 1 + src/ol/source/vectorfilesource.js | 1 + src/ol/source/vectorsource.js | 13 +++++++++++++ 24 files changed, 121 insertions(+), 11 deletions(-) diff --git a/apidoc/plugins/exports.js b/apidoc/plugins/exports.js index c59eab91d4..bd0b263106 100644 --- a/apidoc/plugins/exports.js +++ b/apidoc/plugins/exports.js @@ -1,7 +1,9 @@ /* - * 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 = []; diff --git a/externs/oli.js b/externs/oli.js index 30945f1a70..51e181fc27 100644 --- a/externs/oli.js +++ b/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.} */ @@ -195,7 +195,7 @@ oli.interaction.DragAndDropEvent.prototype.projection; /** @interface */ -oli.render.Event = function() {}; +oli.render.Event; /** @type {CanvasRenderingContext2D|null|undefined} */ diff --git a/src/ol/collection.js b/src/ol/collection.js index f8e44f08b0..6d0fa3e96c 100644 --- a/src/ol/collection.js +++ b/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 diff --git a/src/ol/interaction/draganddropinteraction.js b/src/ol/interaction/draganddropinteraction.js index 7af957e4ee..3a8c5a911d 100644 --- a/src/ol/interaction/draganddropinteraction.js +++ b/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.|undefined} + * @todo stability experimental */ this.features = opt_features; /** * @type {ol.proj.Projection|undefined} + * @todo stability experimental */ this.projection = opt_projection; diff --git a/src/ol/interaction/dragboxinteraction.js b/src/ol/interaction/dragboxinteraction.js index b85a325d44..62ea2488d0 100644 --- a/src/ol/interaction/dragboxinteraction.js +++ b/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 */ diff --git a/src/ol/interaction/drawinteraction.js b/src/ol/interaction/drawinteraction.js index b68e10ab06..226b95bf27 100644 --- a/src/ol/interaction/drawinteraction.js +++ b/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 */ diff --git a/src/ol/layer/heatmaplayer.js b/src/ol/layer/heatmaplayer.js index c0a567c1bd..7cc999dab9 100644 --- a/src/ol/layer/heatmaplayer.js +++ b/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 */ diff --git a/src/ol/layer/imagelayer.js b/src/ol/layer/imagelayer.js index 9f8d1bf4e3..dfa37cfe40 100644 --- a/src/ol/layer/imagelayer.js +++ b/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 */ diff --git a/src/ol/layer/layer.js b/src/ol/layer/layer.js index 4ab377a0a4..b9e7cb6ab5 100644 --- a/src/ol/layer/layer.js +++ b/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 diff --git a/src/ol/layer/tilelayer.js b/src/ol/layer/tilelayer.js index 6f97bf72ce..0d4cfa3ce2 100644 --- a/src/ol/layer/tilelayer.js +++ b/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 diff --git a/src/ol/layer/vectorlayer.js b/src/ol/layer/vectorlayer.js index 1758fae0c5..4e55b7272f 100644 --- a/src/ol/layer/vectorlayer.js +++ b/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 */ diff --git a/src/ol/map.js b/src/ol/map.js index 11d7c9da49..249375e5cf 100644 --- a/src/ol/map.js +++ b/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); diff --git a/src/ol/mapevent.js b/src/ol/mapevent.js index 89cfd8d62f..db97c66063 100644 --- a/src/ol/mapevent.js +++ b/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' }; diff --git a/src/ol/object.js b/src/ol/object.js index 74ef591d68..a786c8205b 100644 --- a/src/ol/object.js +++ b/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.=} opt_values Values. - * @fires ol.ObjectEvent + * @fires {@link ol.ObjectEvent} ol.ObjectEvent * @todo stability experimental */ ol.Object = function(opt_values) { diff --git a/src/ol/observable.js b/src/ol/observable.js index 1d6431ac08..6d1f23d44a 100644 --- a/src/ol/observable.js +++ b/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() { diff --git a/src/ol/render/renderevent.js b/src/ol/render/renderevent.js index 89c443d78f..017b20c276 100644 --- a/src/ol/render/renderevent.js +++ b/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; diff --git a/src/ol/source/geojsonsource.js b/src/ol/source/geojsonsource.js index 67aa42b4ca..1ee7532fd3 100644 --- a/src/ol/source/geojsonsource.js +++ b/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 */ diff --git a/src/ol/source/gpxsource.js b/src/ol/source/gpxsource.js index 5edd1e1a6f..1db7f23603 100644 --- a/src/ol/source/gpxsource.js +++ b/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 */ diff --git a/src/ol/source/igcsource.js b/src/ol/source/igcsource.js index 3548e139e7..c8f19cddfd 100644 --- a/src/ol/source/igcsource.js +++ b/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 */ diff --git a/src/ol/source/kmlsource.js b/src/ol/source/kmlsource.js index 501b84b15c..00b3891a54 100644 --- a/src/ol/source/kmlsource.js +++ b/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 */ diff --git a/src/ol/source/osmxmlsource.js b/src/ol/source/osmxmlsource.js index 48353beda5..b93ca145b2 100644 --- a/src/ol/source/osmxmlsource.js +++ b/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) { diff --git a/src/ol/source/topojsonsource.js b/src/ol/source/topojsonsource.js index 29aff2dadb..991c72afb8 100644 --- a/src/ol/source/topojsonsource.js +++ b/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 */ diff --git a/src/ol/source/vectorfilesource.js b/src/ol/source/vectorfilesource.js index d003037170..e961badd3a 100644 --- a/src/ol/source/vectorfilesource.js +++ b/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 */ diff --git a/src/ol/source/vectorsource.js b/src/ol/source/vectorsource.js index 8168da4736..6383b6dcd9 100644 --- a/src/ol/source/vectorsource.js +++ b/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;