Rename generate-symbols.js to generate-info.js

This task generates build related metadata for the library based on doc annotations.  Since it is about more than writing out exportable symbols, it makes sense to have a more general name.

buildcfg/jsdoc/info/conf.json

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

buildcfg/jsdoc/info/define-plugin.js

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview  This plugin extracts info from boolean defines.  This only
+ * handles boolean defines with the default value in the description.  Default
+ * is assumed to be provided with something like "default is `true`" (case
+ * insensitive, with or without ticks).
+ */
+
+
+var DEFAULT_VALUE = /default\s+is\s+`?(true|false)`?/i;
+
+
+/**
+ * Hook to define new tags.
+ * @param {Object} dictionary The tag dictionary.
+ */
+exports.defineTags = function(dictionary) {
+
+  dictionary.defineTag('define', {
+    canHaveType: true,
+    mustHaveValue: true,
+    onTagged: function(doclet, tag) {
+      var types = tag.value.type.names;
+      if (types.length === 1 && types[0] === 'boolean') {
+        var match = tag.value.description.match(DEFAULT_VALUE);
+        if (match) {
+          doclet.define = {
+            default: match[1] === 'true'
+          };
+        }
+      }
+    }
+  });
+
+};

buildcfg/jsdoc/info/publish.js

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Generates JSON output based on exportable symbols (those with
+ * an api tag) and boolean defines (with a define tag and a default value).
+ */
+var assert = require('assert');
+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 or define (excluding enums,
+  // typedefs and events)
+  var docs = data(
+      [{define: {isObject: true}}, {api: {isString: true}}],
+      {isEnum: {'!is': true}},
+      {kind: {'!is': 'typedef'}},
+      {kind: {'!is': 'event'}}).get();
+
+  // get symbols data, filter out those that are members of private classes
+  var symbols = [];
+  var defines = [];
+  docs.filter(function(doc) {
+    var include = true;
+    var constructor = doc.memberof;
+    if (constructor && constructor.substr(-1) === '_') {
+      assert.strictEqual(doc.inherited, true,
+          'Unexpected export on private class: ' + doc.longname);
+      include = false;
+    }
+    return include;
+  }).forEach(function(doc) {
+    if (doc.define) {
+      defines.push({
+        name: doc.longname,
+        path: path.join(doc.meta.path, doc.meta.filename),
+        default: doc.define.default
+      });
+    } else {
+      symbols.push({
+        name: doc.longname,
+        extends: doc.augments,
+        path: path.join(doc.meta.path, doc.meta.filename)
+      });
+    }
+  });
+
+  process.stdout.write(
+      JSON.stringify({symbols: symbols, defines: defines}, null, 2));
+
+};

buildcfg/jsdoc/info/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();
+      }
+    }
+  });
+
+};