From 50f8eb65fd5aae51c1c5bc12035262fb40da4499 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Mon, 24 Mar 2014 21:53:18 +0100 Subject: [PATCH 01/12] Add capabilities to document events --- apidoc/conf.json | 1 + apidoc/plugins/event.js | 18 ++++++++++++++++++ apidoc/plugins/todo.js | 8 ++++++++ apidoc/template/tmpl/container.tmpl | 12 ++++++++++++ apidoc/template/tmpl/events.tmpl | 21 +++++++++++++++++++++ build.py | 2 +- 6 files changed, 61 insertions(+), 1 deletion(-) create mode 100644 apidoc/plugins/event.js create mode 100644 apidoc/template/tmpl/events.tmpl diff --git a/apidoc/conf.json b/apidoc/conf.json index 8131a4bc6e..42c9f657d7 100644 --- a/apidoc/conf.json +++ b/apidoc/conf.json @@ -21,6 +21,7 @@ "apidoc/plugins/inheritdoc", "apidoc/plugins/exports", "apidoc/plugins/todo", + "apidoc/plugins/event", "apidoc/plugins/observable", "apidoc/plugins/stability" ], diff --git a/apidoc/plugins/event.js b/apidoc/plugins/event.js new file mode 100644 index 0000000000..f1375f9a41 --- /dev/null +++ b/apidoc/plugins/event.js @@ -0,0 +1,18 @@ +var util = require('util'); +exports.defineTags = function(dictionary) { + dictionary.defineTag('event', { + mustHaveValue: true, + canHaveType: false, + canHaveName: true, + onTagged: function(doclet, tag) { + var parts = tag.text.split(' '); + if (!doclet.events) { + doclet.events = []; + } + doclet.events.push({ + name: tag.value.name, + description: parts.slice(1).join(' ') + }); + } + }); +}; diff --git a/apidoc/plugins/todo.js b/apidoc/plugins/todo.js index 1a8a4ec65e..78faccb817 100644 --- a/apidoc/plugins/todo.js +++ b/apidoc/plugins/todo.js @@ -22,6 +22,14 @@ exports.defineTags = function(dictionary) { description: description, readonly: readonly }); + } else if (parts[0] === 'event') { + if (!doclet.events) { + doclet.events = []; + } + doclet.events.push({ + name: parts[1], + description: parts.slice(2).join(' ') + }); } } }); diff --git a/apidoc/template/tmpl/container.tmpl b/apidoc/template/tmpl/container.tmpl index b10f51a72a..3a92ea4e68 100644 --- a/apidoc/template/tmpl/container.tmpl +++ b/apidoc/template/tmpl/container.tmpl @@ -101,6 +101,18 @@ + +

Events

+ +

These events are available in addition to the Observable Properties events listed above.

+ +
+ + + + + + Name + Description + + + + + + + + + + + + diff --git a/build.py b/build.py index 7962522c69..97c1b29dc4 100755 --- a/build.py +++ b/build.py @@ -373,7 +373,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,todo,function', '--strict', t.newer(t.dependencies)) t.touch() From fcd737e62b51bcc9612db4cc8f667da4682595a5 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Mon, 24 Mar 2014 21:53:32 +0100 Subject: [PATCH 02/12] Document MapBrowserEvent events --- src/ol/mapbrowserevent.js | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/ol/mapbrowserevent.js b/src/ol/mapbrowserevent.js index f2b7bdcb99..cc6db482ca 100644 --- a/src/ol/mapbrowserevent.js +++ b/src/ol/mapbrowserevent.js @@ -26,6 +26,19 @@ goog.require('ol.pointer.PointerEventHandler'); * @param {ol.Map} map Map. * @param {goog.events.BrowserEvent} browserEvent Browser event. * @param {?oli.FrameState=} opt_frameState Frame state. + * @event singleclick 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 dblclick A true double click, with no dragging. + * @event pointerdrag Triggered when a pointer is dragged. + * @event pointermove Triggered when a pointer is moved. + * @event pointerdown Triggered on pointer down. + * @event pointerup Triggered on pointer up. + * @event pointerover Triggered when a pointer is over the map's `target`. + * @event pointerout Triggered when a pointer is outside the map's `target`. + * @event pointerenter Triggered when a pointer enters the map's `target`. + * @event pointerleave Triggered when a pointer leaves the map's `target`. + * @event pointercancel Triggered when a pointer is no longer registered. * @todo stability experimental */ ol.MapBrowserEvent = function(type, map, browserEvent, opt_frameState) { From f37245963c59fcb05819ab86ae3fe4186318eb5f Mon Sep 17 00:00:00 2001 From: ahocevar Date: Mon, 24 Mar 2014 21:53:42 +0100 Subject: [PATCH 03/12] Document Map events --- src/ol/map.js | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/src/ol/map.js b/src/ol/map.js index fbe46a52cd..7ff7b1e724 100644 --- a/src/ol/map.js +++ b/src/ol/map.js @@ -153,9 +153,14 @@ ol.MapProperty = { * The above snippet creates a map with a MapQuest OSM layer on a 2D view and * renders it to a DOM element with the id `map`. * + * In addition to the events listed below, the map relays + * {@link ol.MapBrowserEvent} events. + * * @constructor * @extends {ol.Object} * @param {olx.MapOptions} options Map options. + * @event moveend Triggered after the map is moved. + * @event postrender Triggered after a map frame is rendered. * @todo stability experimental * @todo observable layergroup {ol.layer.LayerGroup} a layer group containing * the layers in this map. @@ -163,7 +168,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); @@ -766,7 +771,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 +782,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_; From 7e850ca33d0595c0838461369aeeebf4eb160b8d Mon Sep 17 00:00:00 2001 From: ahocevar Date: Tue, 25 Mar 2014 18:21:08 +0100 Subject: [PATCH 04/12] Use JSDoc's stock event documentation --- apidoc/conf.json | 1 - apidoc/plugins/event.js | 18 ------------------ apidoc/plugins/observable.js | 6 ++++++ apidoc/plugins/todo.js | 12 +++++------- apidoc/template/tmpl/events.tmpl | 21 --------------------- build.py | 2 +- src/ol/map.js | 7 ++----- src/ol/mapbrowserevent.js | 31 ++++++++++++++++++------------- 8 files changed, 32 insertions(+), 66 deletions(-) delete mode 100644 apidoc/plugins/event.js delete mode 100644 apidoc/template/tmpl/events.tmpl diff --git a/apidoc/conf.json b/apidoc/conf.json index 42c9f657d7..8131a4bc6e 100644 --- a/apidoc/conf.json +++ b/apidoc/conf.json @@ -21,7 +21,6 @@ "apidoc/plugins/inheritdoc", "apidoc/plugins/exports", "apidoc/plugins/todo", - "apidoc/plugins/event", "apidoc/plugins/observable", "apidoc/plugins/stability" ], diff --git a/apidoc/plugins/event.js b/apidoc/plugins/event.js deleted file mode 100644 index f1375f9a41..0000000000 --- a/apidoc/plugins/event.js +++ /dev/null @@ -1,18 +0,0 @@ -var util = require('util'); -exports.defineTags = function(dictionary) { - dictionary.defineTag('event', { - mustHaveValue: true, - canHaveType: false, - canHaveName: true, - onTagged: function(doclet, tag) { - var parts = tag.text.split(' '); - if (!doclet.events) { - doclet.events = []; - } - doclet.events.push({ - name: tag.value.name, - description: parts.slice(1).join(' ') - }); - } - }); -}; diff --git a/apidoc/plugins/observable.js b/apidoc/plugins/observable.js index 14bf45a722..772de2c7d4 100644 --- a/apidoc/plugins/observable.js +++ b/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'); + } } }); }; diff --git a/apidoc/plugins/todo.js b/apidoc/plugins/todo.js index 78faccb817..2a2d05a027 100644 --- a/apidoc/plugins/todo.js +++ b/apidoc/plugins/todo.js @@ -22,14 +22,12 @@ exports.defineTags = function(dictionary) { description: description, readonly: readonly }); - } else if (parts[0] === 'event') { - if (!doclet.events) { - doclet.events = []; + 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'); } - doclet.events.push({ - name: parts[1], - description: parts.slice(2).join(' ') - }); } } }); diff --git a/apidoc/template/tmpl/events.tmpl b/apidoc/template/tmpl/events.tmpl deleted file mode 100644 index d93bc97110..0000000000 --- a/apidoc/template/tmpl/events.tmpl +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - - - - - - - - - - - -
NameDescription
diff --git a/build.py b/build.py index 97c1b29dc4..24f9eb0bdd 100755 --- a/build.py +++ b/build.py @@ -373,7 +373,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=event,todo,function', + '--custom_jsdoc_tags=event,fires,todo,function', '--strict', t.newer(t.dependencies)) t.touch() diff --git a/src/ol/map.js b/src/ol/map.js index 7ff7b1e724..11d7c9da49 100644 --- a/src/ol/map.js +++ b/src/ol/map.js @@ -153,14 +153,11 @@ ol.MapProperty = { * The above snippet creates a map with a MapQuest OSM layer on a 2D view and * renders it to a DOM element with the id `map`. * - * In addition to the events listed below, the map relays - * {@link ol.MapBrowserEvent} events. - * * @constructor * @extends {ol.Object} * @param {olx.MapOptions} options Map options. - * @event moveend Triggered after the map is moved. - * @event postrender Triggered after a map frame is rendered. + * @fires {@link ol.MapEvent} ol.MapEvent + * @fires {@link ol.MapBrowserEvent} ol.MapBrowserEvent * @todo stability experimental * @todo observable layergroup {ol.layer.LayerGroup} a layer group containing * the layers in this map. diff --git a/src/ol/mapbrowserevent.js b/src/ol/mapbrowserevent.js index cc6db482ca..60c7235601 100644 --- a/src/ol/mapbrowserevent.js +++ b/src/ol/mapbrowserevent.js @@ -26,19 +26,6 @@ goog.require('ol.pointer.PointerEventHandler'); * @param {ol.Map} map Map. * @param {goog.events.BrowserEvent} browserEvent Browser event. * @param {?oli.FrameState=} opt_frameState Frame state. - * @event singleclick 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 dblclick A true double click, with no dragging. - * @event pointerdrag Triggered when a pointer is dragged. - * @event pointermove Triggered when a pointer is moved. - * @event pointerdown Triggered on pointer down. - * @event pointerup Triggered on pointer up. - * @event pointerover Triggered when a pointer is over the map's `target`. - * @event pointerout Triggered when a pointer is outside the map's `target`. - * @event pointerenter Triggered when a pointer enters the map's `target`. - * @event pointerleave Triggered when a pointer leaves the map's `target`. - * @event pointercancel Triggered when a pointer is no longer registered. * @todo stability experimental */ ol.MapBrowserEvent = function(type, map, browserEvent, opt_frameState) { @@ -473,11 +460,28 @@ 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 + */ SINGLECLICK: 'singleclick', + /** + * A true double click, with no dragging. + * @event ol.MapBrowserEvent#dblclick + */ DBLCLICK: goog.events.EventType.DBLCLICK, + /** + * Triggered when a pointer is dragged. + * @event ol.MapBrowserEvent#pointerdrag + */ POINTERDRAG: 'pointerdrag', // original pointer event types + /** + * Triggered when a pointer is moved. + * @event ol.MapBrowserEvent#pointermove + */ POINTERMOVE: 'pointermove', POINTERDOWN: 'pointerdown', POINTERUP: 'pointerup', @@ -487,3 +491,4 @@ ol.MapBrowserEvent.EventType = { POINTERLEAVE: 'pointerleave', POINTERCANCEL: 'pointercancel' }; + From 026c7149c839a7497ca4e926f8ad553f2f596fef Mon Sep 17 00:00:00 2001 From: ahocevar Date: Tue, 25 Mar 2014 18:21:55 +0100 Subject: [PATCH 05/12] Fix @override documentation --- apidoc/plugins/inheritdoc.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apidoc/plugins/inheritdoc.js b/apidoc/plugins/inheritdoc.js index 136bf385c8..4c2f571844 100644 --- a/apidoc/plugins/inheritdoc.js +++ b/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; } } From d0ac615befb21d61c177e78f1dca05a651749d9e Mon Sep 17 00:00:00 2001 From: ahocevar Date: Tue, 25 Mar 2014 18:23:05 +0100 Subject: [PATCH 06/12] Distinct unexported and undocumented symbols --- apidoc/plugins/exports.js | 19 ++++++++++++++++--- apidoc/template/tmpl/container.tmpl | 3 +-- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/apidoc/plugins/exports.js b/apidoc/plugins/exports.js index 10dded9b00..b1494f7879 100644 --- a/apidoc/plugins/exports.js +++ b/apidoc/plugins/exports.js @@ -5,6 +5,7 @@ */ var api = []; +var unexported = []; function collectExports(source) { var i, ii, symbol, property; @@ -56,7 +57,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 +67,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 +94,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; diff --git a/apidoc/template/tmpl/container.tmpl b/apidoc/template/tmpl/container.tmpl index 3a92ea4e68..67013b8021 100644 --- a/apidoc/template/tmpl/container.tmpl +++ b/apidoc/template/tmpl/container.tmpl @@ -27,8 +27,7 @@ - - + From 7a9353cc872fab362763b0812a070e4f6d6a02e4 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Tue, 25 Mar 2014 18:24:09 +0100 Subject: [PATCH 07/12] Document classes and properties from externs/oli.js --- apidoc/plugins/exports.js | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/apidoc/plugins/exports.js b/apidoc/plugins/exports.js index b1494f7879..c59eab91d4 100644 --- a/apidoc/plugins/exports.js +++ b/apidoc/plugins/exports.js @@ -28,9 +28,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 = { From 4fad17b2134e20f800f2f5f73b6702a4041fd54e Mon Sep 17 00:00:00 2001 From: ahocevar Date: Tue, 25 Mar 2014 18:24:37 +0100 Subject: [PATCH 08/12] Make clearer what the 'Event' for observable properties means --- apidoc/template/tmpl/observables.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apidoc/template/tmpl/observables.tmpl b/apidoc/template/tmpl/observables.tmpl index 018da4308a..8f0e670932 100644 --- a/apidoc/template/tmpl/observables.tmpl +++ b/apidoc/template/tmpl/observables.tmpl @@ -8,7 +8,7 @@ Name Type Settable - Event + ol.ObjectEvent type Description From 3227ce4a0697a68e9ec388c1b1e6a7c8f11d3079 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Tue, 25 Mar 2014 18:24:57 +0100 Subject: [PATCH 09/12] Document ol.ObjectEvent events --- src/ol/object.js | 1 + 1 file changed, 1 insertion(+) diff --git a/src/ol/object.js b/src/ol/object.js index 2b09635a32..74ef591d68 100644 --- a/src/ol/object.js +++ b/src/ol/object.js @@ -99,6 +99,7 @@ ol.ObjectAccessor.prototype.transform = function(from, to) { * @constructor * @extends {ol.Observable} * @param {Object.=} opt_values Values. + * @fires ol.ObjectEvent * @todo stability experimental */ ol.Object = function(opt_values) { From 7fa8bd6723ff40e645d6b51b9315064d490a6585 Mon Sep 17 00:00:00 2001 From: ahocevar Date: Tue, 25 Mar 2014 18:25:05 +0100 Subject: [PATCH 10/12] Document ol.MapEvent events --- src/ol/mapevent.js | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/ol/mapevent.js b/src/ol/mapevent.js index 7c98d685af..89cfd8d62f 100644 --- a/src/ol/mapevent.js +++ b/src/ol/mapevent.js @@ -8,7 +8,15 @@ goog.require('goog.events.Event'); * @enum {string} */ ol.MapEventType = { + /** + * Triggered after a map frame is rendered. + * @event ol.MapEvent#postrender + */ POSTRENDER: 'postrender', + /** + * Triggered after the map is moved. + * @event ol.MapEvent#moveend + */ MOVEEND: 'moveend' }; From 932cab12af6e81088add5638861dc3b1928a157a Mon Sep 17 00:00:00 2001 From: ahocevar Date: Tue, 25 Mar 2014 22:07:14 +0100 Subject: [PATCH 11/12] Document stability of MapBrowserEvent properties and events --- src/ol/mapbrowserevent.js | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/ol/mapbrowserevent.js b/src/ol/mapbrowserevent.js index 60c7235601..f1507d140c 100644 --- a/src/ol/mapbrowserevent.js +++ b/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); @@ -464,16 +467,19 @@ ol.MapBrowserEvent.EventType = { * 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', @@ -481,6 +487,7 @@ ol.MapBrowserEvent.EventType = { /** * Triggered when a pointer is moved. * @event ol.MapBrowserEvent#pointermove + * @todo stability experimental */ POINTERMOVE: 'pointermove', POINTERDOWN: 'pointerdown', @@ -491,4 +498,3 @@ ol.MapBrowserEvent.EventType = { POINTERLEAVE: 'pointerleave', POINTERCANCEL: 'pointercancel' }; - From a3b5376520ff5af50555167bd056d4d642d2ac0b Mon Sep 17 00:00:00 2001 From: ahocevar Date: Wed, 26 Mar 2014 14:04:58 +0100 Subject: [PATCH 12/12] 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;