Build externs file from info.json
This change adds all information that is needed to generate the externs file to build/info.json, so tasks/generate-externs.js no longer needs to spawn JSDoc.
This commit is contained in:
Andreas Hocevar
@@ -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"
|
||||
]
|
||||
}
|
||||
@@ -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'));
|
||||
|
||||
};
|
||||
@@ -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"
|
||||
]
|
||||
}
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
@@ -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.<string>, Array.<Object>)} 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.<Object>} 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.<string>)} 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.<string>} 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);
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user