diff --git a/buildcfg/jsdoc/externs/conf.json b/buildcfg/jsdoc/externs/conf.json deleted file mode 100644 index 0371382163..0000000000 --- a/buildcfg/jsdoc/externs/conf.json +++ /dev/null @@ -1,16 +0,0 @@ -{ - "opts": { - "recurse": true, - "template": "buildcfg/jsdoc/externs" - }, - "tags": { - "allowUnknownTags": true - }, - "source": { - "includePattern": "\\.js$" - }, - "plugins": [ - "buildcfg/jsdoc/api-plugin", - "buildcfg/jsdoc/define-plugin" - ] -} diff --git a/buildcfg/jsdoc/externs/publish.js b/buildcfg/jsdoc/externs/publish.js deleted file mode 100644 index f050be590c..0000000000 --- a/buildcfg/jsdoc/externs/publish.js +++ /dev/null @@ -1,130 +0,0 @@ -/** - * @fileoverview Generates a closure compiler externs file for exportable - * symbols (those with an api tag) and boolean defines (with a define tag and a - * default value). - */ -var assert = require('assert'); -var fs = require('fs'); -var path = require('path'); - - -/** - * Publish hook for the JSDoc template. Writes to stdout. - * @param {function} data The root of the Taffy DB containing doclet records. - * @param {Object} opts Options. - */ -exports.publish = function(data, opts) { - - // get all doclets with the "api" property or define (excluding enums, - // typedefs and events) - var docs = data( - [{define: {isObject: true}}, {api: {isString: true}}], - {isEnum: {'!is': true}}, - {kind: {'!is': 'typedef'}}, - {kind: {'!is': 'event'}}).get(); - - // get symbols data, filter out those that are members of private classes - var output = []; - var namespaces = {}; - var constructors = {}; - docs.filter(function(doc) { - var include = true; - var constructor = doc.memberof; - if (constructor && constructor.substr(-1) === '_') { - assert.strictEqual(doc.inherited, true, - 'Unexpected export on private class: ' + doc.longname); - include = false; - } - return include; - }).forEach(function(doc) { - - var parts = doc.longname.split('#')[0].split('.'); - parts.pop(); - var namespace = []; - parts.forEach(function(part) { - namespace.push(part); - var partialNamespace = namespace.join('.'); - if (!(partialNamespace in namespaces)) { - namespaces[partialNamespace] = true; - output.push('/**'); - output.push(' * @type {Object}'); - output.push(' */'); - output.push( - (namespace.length == 1 ? 'var ' : '') + partialNamespace + ';'); - output.push(''); - } - }); - - var signature = doc.longname; - if (signature.indexOf('#') > 0) { - signature = doc.longname.replace('#', '.prototype.'); - var constructor = doc.longname.split('#')[0]; - if (!(constructor in constructors)) { - constructors[constructor] = true; - output.push('/**'); - output.push(' * @constructor'); - output.push(' */'); - output.push(constructor + ' = function() {}'); - output.push(''); - } - } - - output.push('/**'); - if (doc.define) { - output.push(' * @define'); - output.push(' * @type {boolean}'); - output.push(' */'); - output.push(doc.longname + ';'); - } else { - if (doc.kind == 'class') { - output.push(' * @constructor'); - } - if (doc.type) { - var types = []; - doc.type.names.forEach(function(name) { - types.push(name); - }); - output.push(' * @type {' + types.join('|') + '}'); - } - var args = []; - if (doc.params) { - doc.params.forEach(function(param) { - args.push(param.name); - var names = []; - param.type.names.forEach(function(name) { - names.push(name); - }); - output.push(' * @param {' + - (param.variable ? '...' : '') + - names.join('|') + - (param.optional ? '=' : '') + - '} ' + param.name); - }); - } - if (doc.returns) { - var returnTypes = []; - doc.returns[0].type.names.forEach(function(name) { - returnTypes.push(name); - }); - output.push(' * @return {' + returnTypes.join('|') + '}'); - } - if (doc.tags) { - doc.tags.forEach(function(tag) { - if (tag.title == 'template') { - output.push(' * @' + tag.title + ' ' + tag.value); - } - }); - } - output.push(' */'); - if (doc.kind == 'function' || doc.kind == 'class') { - output.push(signature + ' = function(' + args.join(', ') + ') {};'); - } else { - output.push(signature); - } - } - output.push(''); - }); - - process.stdout.write(output.join('\n')); - -}; diff --git a/buildcfg/jsdoc/api-plugin.js b/buildcfg/jsdoc/info/api-plugin.js similarity index 100% rename from buildcfg/jsdoc/api-plugin.js rename to buildcfg/jsdoc/info/api-plugin.js diff --git a/buildcfg/jsdoc/info/conf.json b/buildcfg/jsdoc/info/conf.json index 3d2c6c6e53..c66f3993ab 100644 --- a/buildcfg/jsdoc/info/conf.json +++ b/buildcfg/jsdoc/info/conf.json @@ -10,7 +10,7 @@ "includePattern": "\\.js$" }, "plugins": [ - "buildcfg/jsdoc/api-plugin", - "buildcfg/jsdoc/define-plugin" + "buildcfg/jsdoc/info/api-plugin", + "buildcfg/jsdoc/info/define-plugin" ] } diff --git a/buildcfg/jsdoc/define-plugin.js b/buildcfg/jsdoc/info/define-plugin.js similarity index 100% rename from buildcfg/jsdoc/define-plugin.js rename to buildcfg/jsdoc/info/define-plugin.js diff --git a/buildcfg/jsdoc/info/publish.js b/buildcfg/jsdoc/info/publish.js index 8badcbf934..1a6e6113b9 100644 --- a/buildcfg/jsdoc/info/publish.js +++ b/buildcfg/jsdoc/info/publish.js @@ -44,12 +44,58 @@ exports.publish = function(data, opts) { default: doc.define.default }); } 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) { + var types = []; + doc.type.names.forEach(function(name) { + types.push(name); + }); + symbol.types = types; + } + if (doc.params) { + var params = []; + doc.params.forEach(function(param) { + var paramInfo = { + name: param.name + }; + params.push(paramInfo); + var types = []; + param.type.names.forEach(function(name) { + types.push(name); + }); + paramInfo.types = types; + if (typeof param.variable == 'boolean') { + paramInfo.variable = param.variable; + } + if (typeof param.optional == 'boolean') { + paramInfo.optional = param.optional; + } + }); + symbol.params = params; + } + if (doc.returns) { + var returns = []; + doc.returns[0].type.names.forEach(function(name) { + returns.push(name); + }); + symbol.returns = returns; + } + if (doc.tags) { + doc.tags.every(function(tag) { + if (tag.title == 'template') { + symbol.template = tag.value; + return false; + } + return true; + }); + } + symbols.push(symbol); } }); diff --git a/tasks/generate-externs.js b/tasks/generate-externs.js index 4498990432..7eaec497bb 100644 --- a/tasks/generate-externs.js +++ b/tasks/generate-externs.js @@ -1,157 +1,160 @@ var fs = require('fs'); var path = require('path'); -var spawn = require('child_process').spawn; var async = require('async'); var fse = require('fs-extra'); -var walk = require('walk').walk; +var nomnom = require('nomnom'); + +var generateInfo = require('./generate-info'); -var sourceDir = path.join(__dirname, '..', 'src'); var olxPath = path.join(__dirname, '..', 'externs', 'olx.js'); -var externsPath = path.join(__dirname, '..', 'build', 'ol-externs.js'); -var jsdoc = path.join(__dirname, '..', 'node_modules', '.bin', 'jsdoc'); -var jsdocConfig = path.join( - __dirname, '..', 'buildcfg', 'jsdoc', 'externs', 'conf.json'); /** - * Get the mtime of the externs file. - * @param {function(Error, Date)} callback Callback called with any - * error and the mtime of the externs file (zero date if it doesn't exist). + * Read the symbols from info file. + * @param {funciton(Error, Array., Array.)} callback Called + * with the patterns and symbols (or any error). */ -function getExternsTime(callback) { - fs.stat(externsPath, function(err, stats) { +function getSymbols(callback) { + generateInfo(function(err) { if (err) { - if (err.code === 'ENOENT') { - callback(null, new Date(0)); + callback(new Error('Trouble generating info: ' + err.message)); + return; + } + var symbols = require('../build/info.json').symbols; + callback(null, symbols); + }); +} + + +/** + * Generate externs code given a list symbols. + * @param {Array.} symbols List of symbols. + * @param {string|undefined} namespace Target object for exported symbols. + * @return {string} Export code. + */ +function generateExterns(symbols) { + var lines = []; + var namespaces = {}; + var constructors = {}; + + symbols.forEach(function(symbol) { + var parts = symbol.name.split('#')[0].split('.'); + parts.pop(); + var namespace = []; + parts.forEach(function(part) { + namespace.push(part); + var partialNamespace = namespace.join('.'); + if (!(partialNamespace in namespaces)) { + namespaces[partialNamespace] = true; + lines.push('/**'); + lines.push(' * @type {Object}'); + lines.push(' */'); + lines.push( + (namespace.length == 1 ? 'var ' : '') + partialNamespace + ';'); + lines.push('\n'); + } + }); + + var name = symbol.name; + if (name.indexOf('#') > 0) { + name = symbol.name.replace('#', '.prototype.'); + var constructor = symbol.name.split('#')[0]; + if (!(constructor in constructors)) { + constructors[constructor] = true; + lines.push('/**'); + lines.push(' * @constructor'); + lines.push(' */'); + lines.push(constructor + ' = function() {};'); + lines.push('\n'); + } + } + + lines.push('/**'); + if ('default' in symbol) { + lines.push(' * @define'); + lines.push(' * @type {boolean}'); + lines.push(' */'); + lines.push(symbol.name + ';'); + } else { + if (symbol.kind == 'class') { + lines.push(' * @constructor'); + } + if (symbol.types) { + lines.push(' * @type {' + symbol.types.join('|') + '}'); + } + var args = []; + if (symbol.params) { + symbol.params.forEach(function(param) { + args.push(param.name); + lines.push(' * @param {' + + (param.variable ? '...' : '') + + param.types.join('|') + + (param.optional ? '=' : '') + + '} ' + param.name); + }); + } + if (symbol.returns) { + lines.push(' * @return {' + symbol.returns.join('|') + '}'); + } + if (symbol.template) { + lines.push(' * @template ' + symbol.template); + } + lines.push(' */'); + if (symbol.kind == 'function' || symbol.kind == 'class') { + lines.push(name + ' = function(' + args.join(', ') + ') {};'); } else { - callback(err); - } - } else { - callback(null, stats.mtime); - } - }); -} - - -/** - * Generate a list of all .js paths in the source directory if any are newer - * than the provided date. - * @param {Date} date Modification time of externs file. - * @param {function(Error, Array.)} callback Called with any - * error and the array of source paths (empty if none newer). - */ -function getNewer(date, callback) { - var paths = []; - var newer = false; - - var walker = walk(sourceDir); - walker.on('file', function(root, stats, next) { - var sourcePath = path.join(root, stats.name); - if (/\.js$/.test(sourcePath)) { - paths.push(sourcePath); - if (stats.mtime > date) { - newer = true; + lines.push(name + ';'); } } - next(); - }); - walker.on('errors', function() { - callback(new Error('Trouble walking ' + sourceDir)); - }); - walker.on('end', function() { - callback(null, newer ? paths : []); + lines.push('\n'); }); + + return lines.join('\n'); } /** - * Spawn JSDoc. - * @param {Array.} paths Paths to source files. - * @param {function(Error, string)} callback Callback called with any error and - * the JSDoc output (new metadata). If provided with an empty list of paths - * the callback will be called with null. - */ -function spawnJSDoc(paths, callback) { - if (paths.length === 0) { - process.nextTick(function() { - callback(null, null); - }); - return; - } - - var output = ''; - var errors = ''; - var cwd = path.join(__dirname, '..'); - var child = spawn(jsdoc, ['-c', jsdocConfig].concat(paths), {cwd: cwd}); - - child.stdout.on('data', function(data) { - output += String(data); - }); - - child.stderr.on('data', function(data) { - errors += String(data); - }); - - child.on('exit', function(code) { - if (code) { - callback(new Error(errors || 'JSDoc failed with no output')); - } else { - callback(null, output); - } - }); -} - - -/** - * Write externs file consisting of externs/olx.js and the JSDoc generated - * externs. - * @param {Object} externs JSDoc generated externs. - * @param {function(Error)} callback Callback. - */ -function writeExterns(externs, callback) { - if (externs) { - var olx; - try { - olx = fs.readFileSync(olxPath, {encoding: 'utf-8'}) - .replace(/ \* @api ?(.*)?(\r\n|\n|\r)/gm, ''); - } catch(e) { - process.nextTick(function() { - callback(null); - }); - } - fse.outputFile(externsPath, olx + '\n\n' + externs, callback); - } else { - process.nextTick(function() { - callback(null); - }); - } -} - - -/** - * Determine if source files have been changed, run JSDoc and write updated - * externs if there are any changes. + * Generate the exports code. * - * @param {function(Error)} callback Called when the externs file has been - * written (or an error occurs). + * @param {function(Error, string)} callback Called with the exports code or any + * error generating it. */ function main(callback) { async.waterfall([ - getExternsTime, - getNewer, - spawnJSDoc, - writeExterns + getSymbols, + function(symbols, done) { + var code, err; + try { + var olx = fs.readFileSync(olxPath, {encoding: 'utf-8'}) + .replace(/ \* @api ?(.*)?(\r\n|\n|\r)/gm, ''); + code = olx + '\n\n' + generateExterns(symbols); + } catch (e) { + err = e; + } + done(err, code); + } ], callback); } /** - * If running this module directly, read the config file and call the main - * function. + * If running this module directly, read the config file, call the main + * function, and write the output file. */ if (require.main === module) { - main(function(err) { + var options = nomnom.options({ + output: { + position: 0, + required: true, + help: 'Output path for the generated externs file.' + } + }).parse(); + + async.waterfall([ + main, + fse.outputFile.bind(fse, options.output) + ], function(err) { if (err) { console.error(err.message); process.exit(1); diff --git a/tasks/readme.md b/tasks/readme.md index 1e5826242e..ad3fff9f8c 100644 --- a/tasks/readme.md +++ b/tasks/readme.md @@ -91,7 +91,10 @@ Called internally to generate a `build/exports.js` file optionally with a limite ## `generate-externs.js` -Can be called to generate a Closure externs file for the full OpenLayers 3 API. The externs file will be placed as `ol-externs.js` in the `build/` directory. +Can be called to generate a Closure externs file for the full OpenLayers 3 API. +See the `--help` option for more detail. + + node tasks/generate-externs.js --help This is useful for projects that use the Closure Compiler to build, but want to use OpenLayers 3 as external library rather than building together with OpenLayers 3.