Adding a JSDoc configuration for generating metadata on exported symbols

This generates info for all symbols annotated with "@todo api" (when Plovr is replaced, this will become "@api").  Generated metadata is written to stdout.  A separate process will handle the output.

buildcfg/jsdoc/symbols/conf.json

@@ -0,0 +1,15 @@
+{
+    "opts": {
+        "recurse": true,
+        "template": "buildcfg/jsdoc/symbols"
+    },
+    "tags": {
+        "allowUnknownTags": true
+    },
+    "source": {
+        "includePattern": "\\.js$"
+    },
+    "plugins": [
+        "buildcfg/jsdoc/symbols/todo-plugin"
+    ]
+}

buildcfg/jsdoc/symbols/publish.js

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Generates JSON output based on doclets with the "api" tag.
+ */
+var fs = require('fs');
+var path = require('path');
+
+
+/**
+ * Publish hook for the JSDoc template.  Writes to JSON stdout.
+ * @param {function} data The root of the Taffy DB containing doclet records.
+ * @param {Object} opts Options.
+ */
+exports.publish = function(data, opts) {
+  var cwd = process.cwd();
+
+  // get all doclets with the "api" property.
+  var docs = data({api: {isString: true}}).get();
+
+  process.stdout.write('{"symbols": [');
+
+  // stream JSON for each doclet
+  docs.forEach(function(doc, i) {
+    var metadata = {
+      name: doc.longname,
+      extends: doc.augments || [],
+      package: doc.api,
+      path: path.join(doc.meta.path, doc.meta.filename)
+    };
+    var sep = i > 0 ? ',' : '';
+    process.stdout.write(sep + JSON.stringify(metadata));
+  });
+
+  process.stdout.write(']}\n');
+
+};

buildcfg/jsdoc/symbols/todo-plugin.js

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview  This plugin should go away when we get rid of Plovr and can
+ * use Closure Compiler's extra_annotation_name option.  Until then, we hijack
+ * the todo tag to add doclet properties for other tags we eventually want to
+ * support.  For example, the "todo api" tag can eventually be replaced with
+ * the "api" tag.
+ */
+
+
+/**
+ * Our hook to define new tags.
+ * @param {Object} dictionary The tag dictionary.
+ */
+exports.defineTags = function(dictionary) {
+
+  dictionary.defineTag('todo', {
+    mustHaveValue: true,
+    onTagged: function(doclet, tag) {
+      var parts = tag.text.split(' ');
+      if (parts[0] === 'api') {
+        doclet.api = parts.slice(1).join(' ').trim();
+      }
+    }
+  });
+
+};