Merge pull request #2479 from ahocevar/generate-externs

Node task to generate externs for OpenLayers 3

buildcfg/jsdoc/info/publish.js

@@ -13,19 +13,33 @@ var path = require('path');
  * @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)
+  function getTypes(data) {
+    var types = [];
+    data.forEach(function(name) {
+      types.push(name.replace(/^function$/, 'Function'));
+    });
+    return types;
+  }
+
+  // get all doclets with the "api" property or define (excluding events) or
+  // with olx namespace
   var docs = data(
-      [{define: {isObject: true}}, {api: {isString: true}}],
-      {isEnum: {'!is': true}},
-      {kind: {'!is': 'typedef'}},
+      [
+        {define: {isObject: true}},
+        {api: {isString: true}},
+        function() {
+          return this.meta && (/[\\\/]externs$/).test(this.meta.path);
+        }
+      ],
+      {kind: {'!is': 'file'}},
       {kind: {'!is': 'event'}}).get();
 
   // get symbols data, filter out those that are members of private classes
   var symbols = [];
   var defines = [];
+  var typedefs = [];
+  var externs = [];
   docs.filter(function(doc) {
     var include = true;
     var constructor = doc.memberof;
@@ -36,24 +50,84 @@ exports.publish = function(data, opts) {
     }
     return include;
   }).forEach(function(doc) {
-    if (doc.define) {
+    var isExterns = (/[\\\/]externs$/).test(doc.meta.path);
+    if (isExterns && doc.longname.indexOf('olx.') === 0) {
+      if (doc.kind == 'typedef') {
+        typedefs.push({
+          name: doc.longname,
+          types: ['{}']
+        });
+      } else {
+        var typedef = typedefs[typedefs.length - 1];
+        var type = typedef.types[0];
+        typedef.types[0] = type
+            .replace(/\}$/, ', ' + doc.longname.split('#')[1] +
+                ': (' + getTypes(doc.type.names).join('|') + ')}')
+            .replace('{, ', '{');
+      }
+    } else if (doc.define) {
       defines.push({
         name: doc.longname,
         description: doc.description,
         path: path.join(doc.meta.path, doc.meta.filename),
         default: doc.define.default
       });
+    } else if (doc.kind == 'typedef' || doc.isEnum === true) {
+      typedefs.push({
+        name: doc.longname,
+        types: getTypes(doc.type.names)
+      });
     } else {
-      symbols.push({
+      var types;
+      var symbol = {
         name: doc.longname,
         kind: doc.kind,
         description: doc.classdesc || doc.description,
         path: path.join(doc.meta.path, doc.meta.filename)
-      });
+      };
+      if (doc.type) {
+        symbol.types = getTypes(doc.type.names);
+      }
+      if (doc.params) {
+        var params = [];
+        doc.params.forEach(function(param) {
+          var paramInfo = {
+            name: param.name
+          };
+          params.push(paramInfo);
+          paramInfo.types = getTypes(param.type.names);
+          if (typeof param.variable == 'boolean') {
+            paramInfo.variable = param.variable;
+          }
+          if (typeof param.optional == 'boolean') {
+            paramInfo.optional = param.optional;
+          }
+        });
+        symbol.params = params;
+      }
+      if (doc.returns) {
+        symbol.returns = getTypes(doc.returns[0].type.names);
+      }
+      if (doc.tags) {
+        doc.tags.every(function(tag) {
+          if (tag.title == 'template') {
+            symbol.template = tag.value;
+            return false;
+          }
+          return true;
+        });
+      }
+      var target = isExterns ? externs : symbols;
+      target.push(symbol);
     }
   });
 
   process.stdout.write(
-      JSON.stringify({symbols: symbols, defines: defines}, null, 2));
+      JSON.stringify({
+        symbols: symbols,
+        defines: defines,
+        typedefs: typedefs,
+        externs: externs
+      }, null, 2));
 
 };