Allow to provide externs for inclusion in info.json

buildcfg/jsdoc/info/publish.js

@@ -22,15 +22,15 @@ exports.publish = function(data, opts) {
     return types;
   }
 
-  var cwd = process.cwd();
-
   // get all doclets with the "api" property or define (excluding events) or
   // with olx namespace
   var docs = data(
       [
         {define: {isObject: true}},
         {api: {isString: true}},
-        {longname: {left: 'olx.'}}
+        function() {
+          return this.meta && (/[\\\/]externs$/).test(this.meta.path);
+        }
       ],
       {kind: {'!is': 'event'}}).get();
 
@@ -38,6 +38,7 @@ exports.publish = function(data, opts) {
   var symbols = [];
   var defines = [];
   var typedefs = [];
+  var externs = [];
   docs.filter(function(doc) {
     var include = true;
     var constructor = doc.memberof;
@@ -113,7 +114,8 @@ exports.publish = function(data, opts) {
           return true;
         });
       }
-      symbols.push(symbol);
+      var target = (/[\\\/]externs$/).test(doc.meta.path) ? externs : symbols;
+      target.push(symbol);
     }
   });
 
@@ -121,7 +123,8 @@ exports.publish = function(data, opts) {
       JSON.stringify({
         symbols: symbols,
         defines: defines,
-        typedefs: typedefs
+        typedefs: typedefs,
+        externs: externs
       }, null, 2));
 
 };

tasks/generate-externs.js

@@ -7,15 +7,12 @@ var nomnom = require('nomnom');
 
 var generateInfo = require('./generate-info');
 
-var olxPath = path.join(__dirname, '..', 'externs', 'olx.js');
-
-
 /**
  * Read the symbols from info file.
  * @param {funciton(Error, Array.<string>, Array.<Object>)} callback Called
  *     with the patterns and symbols (or any error).
  */
-function getTypedefsAndSymbols(callback) {
+function getInfo(callback) {
   generateInfo(function(err) {
     if (err) {
       callback(new Error('Trouble generating info: ' + err.message));
@@ -23,7 +20,8 @@ function getTypedefsAndSymbols(callback) {
     }
     var typedefs = require('../build/info.json').typedefs;
     var symbols = require('../build/info.json').symbols;
-    callback(null, typedefs, symbols);
+    var externs = require('../build/info.json').externs;
+    callback(null, typedefs, symbols, externs);
   });
 }
 
@@ -32,10 +30,11 @@ function getTypedefsAndSymbols(callback) {
  * Generate externs code given a list symbols.
  * @param {Array.<Object>} typedefs List of typedefs.
  * @param {Array.<Object>} symbols List of symbols.
+ * @param {Array.<Object>} externs List of externs.
  * @param {string|undefined} namespace Target object for exported symbols.
  * @return {string} Export code.
  */
-function generateExterns(typedefs, symbols) {
+function generateExterns(typedefs, symbols, externs) {
   var lines = [];
   var namespaces = {};
   var constructors = {};
@@ -60,16 +59,7 @@ function generateExterns(typedefs, symbols) {
     });
   }
 
-  typedefs.forEach(function(typedef) {
-    addNamespaces(typedef.name);
-    lines.push('/**');
-    lines.push(' * @typedef {' + typedef.types.join('|') + '}');
-    lines.push(' */');
-    lines.push(typedef.name + ';');
-    lines.push('\n');
-  });
-
-  symbols.forEach(function(symbol) {
+  function processSymbol(symbol) {
     addNamespaces(symbol.name.split('#')[0]);
 
     var name = symbol.name;
@@ -118,7 +108,19 @@ function generateExterns(typedefs, symbols) {
       lines.push(name + ';');
     }
     lines.push('\n');
+  }
+
+  typedefs.forEach(function(typedef) {
+    addNamespaces(typedef.name);
+    lines.push('/**');
+    lines.push(' * @typedef {' + typedef.types.join('|') + '}');
+    lines.push(' */');
+    lines.push(typedef.name + ';');
+    lines.push('\n');
   });
+
+  externs.forEach(processSymbol);
+  symbols.forEach(processSymbol);
   
   return lines.join('\n');
 }
@@ -132,11 +134,11 @@ function generateExterns(typedefs, symbols) {
  */
 function main(callback) {
   async.waterfall([
-    getTypedefsAndSymbols,
-    function(typedefs, symbols, done) {
+    getInfo,
+    function(typedefs, symbols, externs, done) {
       var code, err;
       try {
-        code = generateExterns(typedefs, symbols);
+        code = generateExterns(typedefs, symbols, externs);
       } catch (e) {
         err = e;
       }

tasks/generate-info.js

@@ -7,7 +7,11 @@ var fse = require('fs-extra');
 var walk = require('walk').walk;
 
 var sourceDir = path.join(__dirname, '..', 'src');
-var olxPath = path.join(__dirname, '..', 'externs', 'olx.js');
+var externsDir = path.join(__dirname, '..', 'externs');
+var externsPaths = [
+  path.join(externsDir, 'olx.js'),
+  path.join(externsDir, 'geojson.js')
+];
 var infoPath = path.join(__dirname, '..', 'build', 'info.json');
 var jsdoc = path.join(__dirname, '..', 'node_modules', '.bin', 'jsdoc');
 var jsdocConfig = path.join(
@@ -41,13 +45,23 @@ function getInfoTime(callback) {
  *     error, the mtime of the info file (zero date if it doesn't exist), and
  *     whether externs/olx.js is newer than that date.
  */
-function getOlxNewer(date, callback) {
-  fs.stat(olxPath, function(err, stats) {
-    if (err) {
-      callback(new Error('Trouble reading ' + olxPath));
-    } else {
-      callback(null, date, stats.mtime > date);
-    }
+function getNewerExterns(date, callback) {
+  var newer = false;
+  var walker = walk(externsDir);
+  walker.on('file', function(root, stats, next) {
+    var sourcePath = path.join(root, stats.name);
+    externsPaths.forEach(function(path) {
+      if (sourcePath == path && stats.mtime > date) {
+        newer = true;
+      }
+    });
+    next();
+  });
+  walker.on('errors', function() {
+    callback(new Error('Trouble walking ' + sourceDir));
+  });
+  walker.on('end', function() {
+    callback(null, date, newer);
   });
 }
 
@@ -61,7 +75,7 @@ function getOlxNewer(date, callback) {
  *     error and the array of source paths (empty if none newer).
  */
 function getNewer(date, newer, callback) {
-  var paths = [olxPath];
+  var paths = [].concat(externsPaths);
 
   var walker = walk(sourceDir);
   walker.on('file', function(root, stats, next) {
@@ -238,7 +252,7 @@ function writeInfo(info, callback) {
 function main(callback) {
   async.waterfall([
     getInfoTime,
-    getOlxNewer,
+    getNewerExterns,
     getNewer,
     spawnJSDoc,
     addSymbolProvides,