mirror of
https://github.com/scratchfoundation/paper.js.git
synced 2025-07-29 23:29:06 -04:00
Add typescript definition generation
This add a gulp task (`gulp docs:typescript`) to automatically generate a typescript definition for the library. This should solve the problem of having an out of sync type definition when we change the API. This task takes advantage of existing JSDoc parsing to generate a temporary file which is later formatted through a mustache template to generate the final definition. This definition is then tested by compiling a typescript file that use it. The generated definition is added to the `gulp zip` task in order to be published along with the bundled library. So 2 new dev-dependencies are added with this change: `mustache` and `typescript` packages. Using node and mustache to generate the definition instead of relying on existing templating system is motivated by a better development experience, with easier debugging possibilities... through the usage of more modern tools. As a side note, support of "rest parameters" (when a parameter can be present multiple times) is added to existing JSDoc parser in order to support this pattern on typescript side (E.g. for `Color#set()` method which accept any sequence of parameters that is supported by `Color` constructors).
This commit is contained in:
parent
0cced9788c
commit
bbd65324bc
11 changed files with 1591 additions and 9 deletions
gulp/tasks
|
@ -14,14 +14,15 @@ var gulp = require('gulp'),
|
|||
del = require('del'),
|
||||
rename = require('gulp-rename'),
|
||||
shell = require('gulp-shell'),
|
||||
options = require('../utils/options.js');
|
||||
options = require('../utils/options.js'),
|
||||
run = require('run-sequence');
|
||||
|
||||
var docOptions = {
|
||||
local: 'docs', // Generates the offline docs
|
||||
server: 'serverdocs' // Generates the website templates for the online docs
|
||||
};
|
||||
|
||||
gulp.task('docs', ['docs:local', 'build:full'], function() {
|
||||
gulp.task('docs', ['docs:local', 'docs:typescript', 'build:full'], function() {
|
||||
return gulp.src('dist/paper-full.js')
|
||||
.pipe(rename({ basename: 'paper' }))
|
||||
.pipe(gulp.dest('dist/docs/assets/js/'));
|
||||
|
@ -32,15 +33,57 @@ Object.keys(docOptions).forEach(function(name) {
|
|||
var mode = docOptions[name];
|
||||
return gulp.src('src')
|
||||
.pipe(shell(
|
||||
['java -cp jsrun.jar:lib/* JsRun app/run.js',
|
||||
' -c=conf/', name, '.conf ',
|
||||
' -D="renderMode:', mode, '" ',
|
||||
' -D="version:', options.version, '"'].join(''),
|
||||
[
|
||||
'java -cp jsrun.jar:lib/* JsRun app/run.js',
|
||||
' -c=conf/', name, '.conf ',
|
||||
' -D="renderMode:', mode, '" ',
|
||||
' -D="version:', options.version, '"'
|
||||
].join(''),
|
||||
{ cwd: 'gulp/jsdoc' })
|
||||
)
|
||||
);
|
||||
});
|
||||
|
||||
gulp.task('clean:docs:' + name, function() {
|
||||
return del([ 'dist/' + docOptions[name] + '/**' ]);
|
||||
return del(['dist/' + docOptions[name] + '/**']);
|
||||
});
|
||||
});
|
||||
|
||||
// The goal of the typescript task is to automatically generate a type
|
||||
// definition for the library.
|
||||
gulp.task('docs:typescript', function() {
|
||||
return run(
|
||||
'docs:typescript:clean:before',
|
||||
'docs:typescript:build',
|
||||
'docs:typescript:clean:after'
|
||||
);
|
||||
});
|
||||
// First clean eventually existing type definition...
|
||||
gulp.task('docs:typescript:clean:before', function() {
|
||||
return del('dist/index.d.ts');
|
||||
});
|
||||
// ...then build the definition...
|
||||
gulp.task('docs:typescript:build', function() {
|
||||
// First parse JSDoc comments and store parsed data in a temporary file...
|
||||
return gulp.src('src')
|
||||
.pipe(shell(
|
||||
[
|
||||
'java -cp jsrun.jar:lib/* JsRun app/run.js',
|
||||
' -c=conf/typescript.conf ',
|
||||
' -D="file:../../gulp/typescript/typescript-definition-data.json"',
|
||||
' -D="version:', options.version, '"',
|
||||
' -D="date:', options.date, '"'
|
||||
].join(''),
|
||||
{ cwd: 'gulp/jsdoc' })
|
||||
)
|
||||
// ...then generate definition from parsed data...
|
||||
.pipe(shell('node gulp/typescript/typescript-definition-generator.js'))
|
||||
// ...finally test the definition by compiling a typescript file.
|
||||
.pipe(shell('node node_modules/typescript/bin/tsc gulp/typescript/typescript-definition-test.ts'));
|
||||
});
|
||||
// ...finally remove all unneeded temporary files that were used for building.
|
||||
gulp.task('docs:typescript:clean:after', function() {
|
||||
return del([
|
||||
'gulp/typescript/typescript-definition-data.json',
|
||||
'gulp/typescript/typescript-definition-test.js'
|
||||
]);
|
||||
});
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue