Add base classes to info.json and generated externs

This ensures that the inheritance chain is intact, even if the base
class is not exportable.

config/jsdoc/info/conf.json

@@ -12,6 +12,6 @@
     "plugins": [
         "config/jsdoc/info/api-plugin",
         "config/jsdoc/info/define-plugin",
-        "config/jsdoc/info/interface-plugin"
+        "config/jsdoc/info/virtual-plugin"
     ]
 }

config/jsdoc/info/publish.js

@@ -14,9 +14,6 @@ var path = require('path');
  */
 exports.publish = function(data, opts) {
 
-  var exportables = {};
-  var classes = {};
-
   function getTypes(data) {
     var types = [];
     data.forEach(function(name) {
@@ -25,18 +22,29 @@ exports.publish = function(data, opts) {
     return types;
   }
 
+  function replaceUnknownTypes(item) {
+    item.types.forEach(function(type, index) {
+      if (!(type in names)) {
+        item.types[index] = '*';
+      }
+    });
+  }
+
   // get all doclets with the "api" property or define (excluding events) or
   // with olx namespace
+  var classes = {};
   var docs = data(
       [
         {define: {isObject: true}},
-        {api: {isString: true}},
-        {'interface': {is: true}},
         function() {
           if (this.kind == 'class') {
-            classes[this.longname] = this;
+            if (!('extends' in this) || typeof this.api == 'string') {
+              classes[this.longname] = this;
+              return true;
+            }
           }
-          return this.meta && (/[\\\/]externs$/).test(this.meta.path);
+          return (typeof this.api == 'string' ||
+              this.meta && (/[\\\/]externs$/).test(this.meta.path));
         }
       ],
       {kind: {'!is': 'file'}},
@@ -47,7 +55,9 @@ exports.publish = function(data, opts) {
   var defines = [];
   var typedefs = [];
   var externs = [];
-  var interfaces = [];
+  var base = [];
+  var augments = {};
+  var names = {};
   docs.filter(function(doc) {
     var include = true;
     var constructor = doc.memberof;
@@ -97,6 +107,9 @@ exports.publish = function(data, opts) {
       if (doc.augments) {
         symbol.extends = doc.augments[0];
       }
+      if (doc.virtual) {
+        symbol.virtual = true;
+      }
       if (doc.type) {
         symbol.types = getTypes(doc.type.names);
       }
@@ -137,28 +150,43 @@ exports.publish = function(data, opts) {
           return true;
         });
       }
-      var target = isExterns ? externs : (doc.interface ? interfaces : symbols);
-      target.push(symbol);
 
-      if (symbol.stability && symbol.kind == 'class') {
+      var target = isExterns ? externs : (doc.api ? symbols : base);
-        exportables[symbol.name] = true;
+      target.push(symbol);
-      }
+      names[symbol.name] = true;
-      if (symbol.extends) {
+
-        while (!(symbol.extends in exportables) &&
+      if (doc.api && symbol.extends) {
-            symbol.extends in classes && classes[symbol.extends].augments) {
+        while (symbol.extends in classes && !classes[symbol.extends].api &&
+            classes[symbol.extends].augments) {
           symbol.extends = classes[symbol.extends].augments[0];
         }
+        if (symbol.extends) {
+          augments[symbol.extends] = true;
+        }
       }
     }
   });
 
+  base = base.filter(function(symbol) {
+    var pass = symbol.name in augments || symbol.virtual;
+    if (pass) {
+      if (symbol.params) {
+        symbol.params.forEach(replaceUnknownTypes);
+      }
+      if (symbol.returns) {
+        symbol.returns.forEach(replaceUnknownTypes);
+      }
+    }
+    return pass;
+  });
+
   process.stdout.write(
       JSON.stringify({
         symbols: symbols,
         defines: defines,
         typedefs: typedefs,
         externs: externs,
-        interfaces: interfaces
+        base: base
       }, null, 2));
 
 };

config/jsdoc/info/virtual-plugin.js

@@ -1,5 +1,5 @@
 /**
- * Handle the interface annotation.
+ * Handle the interface and abstract annotations.
  * @param {Object} dictionary The tag dictionary.
  */
 exports.defineTags = function(dictionary) {
@@ -9,7 +9,7 @@ exports.defineTags = function(dictionary) {
     mustHaveValue: false,
     onTagged: function(doclet, tag) {
       classTag.onTagged.apply(this, arguments);
-      doclet.interface = true;
+      doclet.virtual = true;
     }
   });
 

tasks/generate-externs.js

@@ -21,7 +21,7 @@ function getInfo(callback) {
       return;
     }
     var info = require('../build/info.json');
-    callback(null, info.typedefs, info.symbols, info.externs, info.interfaces);
+    callback(null, info.typedefs, info.symbols, info.externs, info.base);
   });
 }
 
@@ -31,11 +31,11 @@ function getInfo(callback) {
  * @param {Array.<Object>} typedefs List of typedefs.
  * @param {Array.<Object>} symbols List of symbols.
  * @param {Array.<Object>} externs List of externs.
- * @param {Array.<Object>} externs List of interfaces.
+ * @param {Array.<Object>} base List of base.
  * @param {string|undefined} namespace Target object for exported symbols.
  * @return {string} Export code.
  */
-function generateExterns(typedefs, symbols, externs, interfaces) {
+function generateExterns(typedefs, symbols, externs, base) {
   var lines = [];
   var processedSymbols = {};
   var constructors = {};
@@ -132,7 +132,7 @@ function generateExterns(typedefs, symbols, externs, interfaces) {
 
   externs.forEach(processSymbol);
 
-  interfaces.forEach(processSymbol);
+  base.forEach(processSymbol);
 
   symbols.forEach(processSymbol);
 
@@ -158,10 +158,10 @@ function generateExterns(typedefs, symbols, externs, interfaces) {
 function main(callback) {
   async.waterfall([
     getInfo,
-    function(typedefs, symbols, externs, interfaces, done) {
+    function(typedefs, symbols, externs, base, done) {
       var code, err;
       try {
-        code = generateExterns(typedefs, symbols, externs, interfaces);
+        code = generateExterns(typedefs, symbols, externs, base);
       } catch (e) {
         err = e;
       }