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$"
|
"includePattern": "\\.js$"
|
||||||
},
|
},
|
||||||
"plugins": [
|
"plugins": [
|
||||||
"buildcfg/jsdoc/api-plugin",
|
"buildcfg/jsdoc/info/api-plugin",
|
||||||
"buildcfg/jsdoc/define-plugin"
|
"buildcfg/jsdoc/info/define-plugin"
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -44,12 +44,58 @@ exports.publish = function(data, opts) {
|
|||||||
default: doc.define.default
|
default: doc.define.default
|
||||||
});
|
});
|
||||||
} else {
|
} else {
|
||||||
symbols.push({
|
var types;
|
||||||
|
var symbol = {
|
||||||
name: doc.longname,
|
name: doc.longname,
|
||||||
kind: doc.kind,
|
kind: doc.kind,
|
||||||
description: doc.classdesc || doc.description,
|
description: doc.classdesc || doc.description,
|
||||||
path: path.join(doc.meta.path, doc.meta.filename)
|
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 fs = require('fs');
|
||||||
var path = require('path');
|
var path = require('path');
|
||||||
var spawn = require('child_process').spawn;
|
|
||||||
|
|
||||||
var async = require('async');
|
var async = require('async');
|
||||||
var fse = require('fs-extra');
|
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 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.
|
* Read the symbols from info file.
|
||||||
* @param {function(Error, Date)} callback Callback called with any
|
* @param {funciton(Error, Array.<string>, Array.<Object>)} callback Called
|
||||||
* error and the mtime of the externs file (zero date if it doesn't exist).
|
* with the patterns and symbols (or any error).
|
||||||
*/
|
*/
|
||||||
function getExternsTime(callback) {
|
function getSymbols(callback) {
|
||||||
fs.stat(externsPath, function(err, stats) {
|
generateInfo(function(err) {
|
||||||
if (err) {
|
if (err) {
|
||||||
if (err.code === 'ENOENT') {
|
callback(new Error('Trouble generating info: ' + err.message));
|
||||||
callback(null, new Date(0));
|
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 {
|
} else {
|
||||||
callback(err);
|
lines.push(name + ';');
|
||||||
}
|
|
||||||
} 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;
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
next();
|
lines.push('\n');
|
||||||
});
|
|
||||||
walker.on('errors', function() {
|
|
||||||
callback(new Error('Trouble walking ' + sourceDir));
|
|
||||||
});
|
|
||||||
walker.on('end', function() {
|
|
||||||
callback(null, newer ? paths : []);
|
|
||||||
});
|
});
|
||||||
|
|
||||||
|
return lines.join('\n');
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Spawn JSDoc.
|
* Generate the exports code.
|
||||||
* @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.
|
|
||||||
*
|
*
|
||||||
* @param {function(Error)} callback Called when the externs file has been
|
* @param {function(Error, string)} callback Called with the exports code or any
|
||||||
* written (or an error occurs).
|
* error generating it.
|
||||||
*/
|
*/
|
||||||
function main(callback) {
|
function main(callback) {
|
||||||
async.waterfall([
|
async.waterfall([
|
||||||
getExternsTime,
|
getSymbols,
|
||||||
getNewer,
|
function(symbols, done) {
|
||||||
spawnJSDoc,
|
var code, err;
|
||||||
writeExterns
|
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);
|
], callback);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* If running this module directly, read the config file and call the main
|
* If running this module directly, read the config file, call the main
|
||||||
* function.
|
* function, and write the output file.
|
||||||
*/
|
*/
|
||||||
if (require.main === module) {
|
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) {
|
if (err) {
|
||||||
console.error(err.message);
|
console.error(err.message);
|
||||||
process.exit(1);
|
process.exit(1);
|
||||||
|
|||||||
@@ -91,7 +91,10 @@ Called internally to generate a `build/exports.js` file optionally with a limite
|
|||||||
|
|
||||||
## `generate-externs.js`
|
## `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.
|
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