From 9800b3825095b2aaa1dfcf38c1d58e107b1b584a Mon Sep 17 00:00:00 2001
From: Tim Schaub <tim.schaub@gmail.com>
Date: Wed, 5 Feb 2014 18:30:14 -0700
Subject: [PATCH] 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      | 15 ++++++++++++
 buildcfg/jsdoc/symbols/publish.js     | 35 +++++++++++++++++++++++++++
 buildcfg/jsdoc/symbols/todo-plugin.js | 26 ++++++++++++++++++++
 3 files changed, 76 insertions(+)
 create mode 100644 buildcfg/jsdoc/symbols/conf.json
 create mode 100644 buildcfg/jsdoc/symbols/publish.js
 create mode 100644 buildcfg/jsdoc/symbols/todo-plugin.js

diff --git a/buildcfg/jsdoc/symbols/conf.json b/buildcfg/jsdoc/symbols/conf.json
new file mode 100644
index 0000000000..29f6b31ecd
--- /dev/null
+++ b/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"
+    ]
+}
diff --git a/buildcfg/jsdoc/symbols/publish.js b/buildcfg/jsdoc/symbols/publish.js
new file mode 100644
index 0000000000..005204652f
--- /dev/null
+++ b/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');
+
+};
diff --git a/buildcfg/jsdoc/symbols/todo-plugin.js b/buildcfg/jsdoc/symbols/todo-plugin.js
new file mode 100644
index 0000000000..4eed6567b2
--- /dev/null
+++ b/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();
+      }
+    }
+  });
+
+};