Use JSDoc's stock event documentation

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"
     ],

apidoc/plugins/event.js

@@ -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(' ')
-      });
-    }
-  });
-};

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,14 +22,12 @@ exports.defineTags = function(dictionary) {
           description: description,
           readonly: readonly
         });
-      } else if (parts[0] === 'event') {
+        if (!doclet.fires) {
-        if (!doclet.events) {
+          doclet.fires = [];
-          doclet.events = [];
+        }
+        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(' ')
-        });
       }
     }
   });

apidoc/template/tmpl/events.tmpl

@@ -1,21 +0,0 @@
-<table class="props">
-    <thead>
-  <tr>
-    <th>Name</th>
-    <th class="last">Description</th>
-  </tr>
-  </thead>
-
-  <tbody>
-  <?js
-      obj.forEach(function(prop) {
-        if (!prop) { return; }
-        var setter = prop.readonly ? 'no' : 'yes';
-  ?>
-    <tr>
-      <td class="name"><code><?js= prop.name ?></code></td>
-      <td class="description last"><?js= prop.description ?></td>
-    </tr>
-    <?js }); ?>
-  </tbody>
-</table>

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()

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.
+ * @fires {@link ol.MapEvent} ol.MapEvent
- * @event postrender Triggered after a map frame is rendered.
+ * @fires {@link ol.MapBrowserEvent} ol.MapBrowserEvent
  * @todo stability experimental
  * @todo observable layergroup {ol.layer.LayerGroup} a layer group containing
  *       the layers in this map.

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'
 };
+