From aaf6101d0f10fe8f502a75876341fb737beed387 Mon Sep 17 00:00:00 2001
From: Andreas Hocevar <andreas.hocevar@gmail.com>
Date: Fri, 11 Apr 2014 23:02:49 +0200
Subject: [PATCH] Include symbols from oli.js using interface and implements
 tags

Instead of regex parsing, we define tags for interface and
implements.
---
 apidoc/conf.json            |  2 ++
 apidoc/plugins/exports.js   | 26 ++++++++++----------------
 apidoc/plugins/interface.js | 23 +++++++++++++++++++++++
 3 files changed, 35 insertions(+), 16 deletions(-)
 create mode 100644 apidoc/plugins/interface.js

diff --git a/apidoc/conf.json b/apidoc/conf.json
index 4b91b0d4b8..d140f56144 100644
--- a/apidoc/conf.json
+++ b/apidoc/conf.json
@@ -14,12 +14,14 @@
         ],
         "include": [
             "src",
+            "externs/oli.js",
             "externs/olx.js"
         ]
     },
     "plugins": [
         "node_modules/jsdoc/plugins/markdown",
         "apidoc/plugins/inheritdoc",
+        "apidoc/plugins/interface",
         "apidoc/plugins/exports",
         "apidoc/plugins/todo",
         "apidoc/plugins/observable",
diff --git a/apidoc/plugins/exports.js b/apidoc/plugins/exports.js
index 7d2f147269..2ef39945a4 100644
--- a/apidoc/plugins/exports.js
+++ b/apidoc/plugins/exports.js
@@ -1,6 +1,5 @@
 /*
- * This plugin parses externs/oli.js as well as goog.exportSymbol and
- * goog.exportProperty calls to build a list of API symbols and properties.
+ * This plugin removes unexported symbols from the documentation.
  * Unexported modules linked from @param or @fires will be marked unexported,
  * and the documentation will not contain the constructor. Everything else is
  * marked undocumented, which will remove it from the docs.
@@ -17,22 +16,9 @@ function collectExports(source) {
   }
 }
 
-function collectOliExports(source) {
-  var oli = source.match(/[^\{]oli\.([^;^ ]*);? ?/g);
-  if (oli) {
-    i = 0; ii = oli.length;
-    for (; i < ii; ++i) {
-      property = 'ol.' + oli[i].match(/oli.([^;]*)/)[1]
-          .replace('.prototype.', '#');
-      unexported.push(property);
-    }
-  }
-}
-
 var encoding = env.conf.encoding || 'utf8';
 var fs = require('jsdoc/fs');
 collectExports(fs.readFileSync('build/symbols.json', encoding));
-collectOliExports(fs.readFileSync('externs/oli.js', encoding));
 
 
 exports.handlers = {
@@ -42,6 +28,9 @@ exports.handlers = {
     if (e.doclet.meta.filename == "olx.js" && e.doclet.longname != 'olx') {
       api.push(e.doclet.longname);
     }
+    if (e.doclet.longname.indexOf('oli.') === 0) {
+      unexported.push(e.doclet.longname.replace(/^oli\./, 'ol.'));
+    }
     if (api.indexOf(e.doclet.longname) > -1) {
       var names, name;
       var params = e.doclet.params;
@@ -87,7 +76,7 @@ exports.handlers = {
               doclet.properties = [];
             }
             doclet.properties.unshift(propertyDoclet);
-            e.doclets.splice(i, 1)
+            e.doclets.splice(i, 1);
           }
         }
       }
@@ -104,6 +93,11 @@ exports.handlers = {
             continue;
           }
         }
+        if (doclet.memberof && doclet.memberof.indexOf('oli.') === 0 &&
+            unexported.indexOf(doclet.memberof) > -1) {
+          // Always document members of referenced oli interfaces
+          continue;
+        }
         doclet.unexported = (api.indexOf(fqn) === -1 && unexported.indexOf(fqn) !== -1);
         if (api.indexOf(fqn) === -1 && unexported.indexOf(fqn) === -1) {
           e.doclets.splice(j, 1);
diff --git a/apidoc/plugins/interface.js b/apidoc/plugins/interface.js
new file mode 100644
index 0000000000..2d4ee8e2a3
--- /dev/null
+++ b/apidoc/plugins/interface.js
@@ -0,0 +1,23 @@
+var util = require('util');
+exports.defineTags = function(dictionary) {
+
+  var classTag = dictionary.lookUp('class');
+  dictionary.defineTag('interface', {
+    mustHaveValue: false,
+    onTagged: function(doclet, tag) {
+      classTag.onTagged.apply(this, arguments);
+      doclet.interface = true;
+    }
+  });
+
+  dictionary.defineTag('implements', {
+    mustHaveValue: true,
+    onTagged: function(doclet, tag) {
+      if (!doclet.implements) {
+        doclet.implements = [];
+      }
+      doclet.implements.push(tag.value.match(/^{(.*)}$/)[1]);
+    }
+  });
+
+};