Add capabilities to document events

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

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

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

apidoc/template/tmpl/container.tmpl

@@ -101,6 +101,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/events.tmpl

@@ -0,0 +1,21 @@
+<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=todo,function',
+          '--custom_jsdoc_tags=event,todo,function',
           '--strict',
           t.newer(t.dependencies))
     t.touch()