diff --git a/config/jsdoc/api/conf.json b/config/jsdoc/api/conf.json index dc8374343c..1e20f46629 100644 --- a/config/jsdoc/api/conf.json +++ b/config/jsdoc/api/conf.json @@ -16,7 +16,7 @@ ] }, "plugins": [ - "node_modules/jsdoc/plugins/markdown", + "node_modules/jsdoc-fork/plugins/markdown", "config/jsdoc/api/plugins/inheritdoc", "config/jsdoc/api/plugins/typedefs", "config/jsdoc/api/plugins/events", diff --git a/config/jsdoc/api/plugins/api.js b/config/jsdoc/api/plugins/api.js index cfed4a7580..9ccc10ed92 100644 --- a/config/jsdoc/api/plugins/api.js +++ b/config/jsdoc/api/plugins/api.js @@ -16,7 +16,7 @@ exports.defineTags = function(dictionary) { doclet.stability = level; } else { var errorText = util.format('Invalid stability level (%s) in %s line %s', tag.text, doclet.meta.filename, doclet.meta.lineno); - require('jsdoc/util/error').handle( new Error(errorText) ); + require('jsdoc-fork/lib/jsdoc/util/error').handle( new Error(errorText) ); } } }); diff --git a/config/jsdoc/api/template/publish.js b/config/jsdoc/api/template/publish.js index eabc52e13a..c1a6801c70 100644 --- a/config/jsdoc/api/template/publish.js +++ b/config/jsdoc/api/template/publish.js @@ -1,10 +1,10 @@ /*global env: true */ -var template = require('jsdoc/template'), - fs = require('jsdoc/fs'), - path = require('jsdoc/path'), +var template = require('jsdoc-fork/lib/jsdoc/template'), + fs = require('jsdoc-fork/lib/jsdoc/fs'), + path = require('jsdoc-fork/lib/jsdoc/path'), taffy = require('taffydb').taffy, - handle = require('jsdoc/util/error').handle, - helper = require('jsdoc/util/templateHelper'), + handle = require('jsdoc-fork/lib/jsdoc/util/error').handle, + helper = require('jsdoc-fork/lib/jsdoc/util/templateHelper'), _ = require('underscore'), htmlsafe = helper.htmlsafe, linkto = helper.linkto, @@ -29,9 +29,9 @@ function getAncestorLinks(doclet) { function hashToLink(doclet, hash) { if ( !/^(#.+)/.test(hash) ) { return hash; } - + var url = helper.createLink(doclet); - + url = url.replace(/(#.+|$)/, hash); return '' + hash + ''; } @@ -59,15 +59,15 @@ function needsSignature(doclet) { function addSignatureParams(f) { var params = helper.getSignatureParams(f, 'optional'); - + f.signature = (f.signature || '') + '('+params.join(', ')+')'; } function addSignatureReturns(f) { var returnTypes = helper.getSignatureReturns(f); - + f.signature = ''+(f.signature || '') + ''; - + if (returnTypes.length) { f.signature += ''+(returnTypes.length ? '{'+returnTypes.join('|')+'}' : '')+''; } @@ -75,7 +75,7 @@ function addSignatureReturns(f) { function addSignatureTypes(f) { var types = helper.getSignatureTypes(f); - + f.signature = (f.signature || '') + ''+(types.length? ' :'+types.join('|') : '')+' '; } @@ -106,7 +106,7 @@ function getPathFromDoclet(doclet) { return filepath; } - + function generate(title, docs, filename, resolveLinks) { resolveLinks = resolveLinks === false ? false : true; @@ -115,14 +115,14 @@ function generate(title, docs, filename, resolveLinks) { title: title, docs: docs }; - + var outpath = path.join(outdir, filename), html = view.render('container.tmpl', docData); - + if (resolveLinks) { html = helper.resolveLinks(html); // turn {@link foo} into foo } - + fs.writeFileSync(outpath, html, 'utf8'); } @@ -153,7 +153,7 @@ function generateSourceFiles(sourceFiles) { * exports only that class or function), then attach the classes or functions to the `module` * property of the appropriate module doclets. The name of each class or function is also updated * for display purposes. This function mutates the original arrays. - * + * * @private * @param {Array.} doclets - The array of classes and functions to * check. @@ -268,7 +268,7 @@ exports.publish = function(taffyData, opts, tutorials) { var templatePath = opts.template; view = new template.Template(templatePath + '/tmpl'); - + // claim some special filenames in advance, so the All-Powerful Overseer of Filename Uniqueness // doesn't try to hand them out later var indexUrl = helper.getUniqueFilename('index'); @@ -291,16 +291,16 @@ exports.publish = function(taffyData, opts, tutorials) { var sourceFilePaths = []; data().each(function(doclet) { doclet.attribs = ''; - + if (doclet.examples) { doclet.examples = doclet.examples.map(function(example) { var caption, code; - + if (example.match(/^\s*([\s\S]+?)<\/caption>(\s*[\n\r])([\s\S]+)$/i)) { caption = RegExp.$1; code = RegExp.$3; } - + return { caption: caption || '', code: code || example @@ -326,7 +326,7 @@ exports.publish = function(taffyData, opts, tutorials) { sourceFilePaths.push(resolvedSourcePath); } }); - + // update outdir if necessary, then create outdir var packageInfo = ( find({kind: 'package'}) || [] ) [0]; if (packageInfo && packageInfo.name) { @@ -350,8 +350,8 @@ exports.publish = function(taffyData, opts, tutorials) { var staticFileScanner; if (conf['default'].staticFiles) { staticFilePaths = conf['default'].staticFiles.paths || []; - staticFileFilter = new (require('jsdoc/src/filter')).Filter(conf['default'].staticFiles); - staticFileScanner = new (require('jsdoc/src/scanner')).Scanner(); + staticFileFilter = new (require('jsdoc-fork/lib/jsdoc/src/filter')).Filter(conf['default'].staticFiles); + staticFileScanner = new (require('jsdoc-fork/lib/jsdoc/src/scanner')).Scanner(); staticFilePaths.forEach(function(filePath) { var extraStaticFiles = staticFileScanner.scan([filePath], 10, staticFileFilter); @@ -365,7 +365,7 @@ exports.publish = function(taffyData, opts, tutorials) { }); }); } - + if (sourceFilePaths.length) { sourceFiles = shortenPaths( sourceFiles, path.commonPrefix(sourceFilePaths) ); } @@ -383,7 +383,7 @@ exports.publish = function(taffyData, opts, tutorials) { } } }); - + data().each(function(doclet) { var url = helper.longnameToUrl[doclet.longname]; @@ -393,13 +393,13 @@ exports.publish = function(taffyData, opts, tutorials) { else { doclet.id = doclet.name; } - + if ( needsSignature(doclet) ) { addSignatureParams(doclet); addSignatureReturns(doclet); } }); - + // do this after the urls have all been generated data().each(function(doclet) { doclet.ancestors = getAncestorLinks(doclet); @@ -407,13 +407,13 @@ exports.publish = function(taffyData, opts, tutorials) { if (doclet.kind === 'member') { addSignatureTypes(doclet); } - + if (doclet.kind === 'constant') { addSignatureTypes(doclet); doclet.kind = 'member'; } }); - + var members = helper.getMembers(data); members.tutorials = tutorials.children; @@ -437,7 +437,7 @@ exports.publish = function(taffyData, opts, tutorials) { } if (members.globals.length) { generate('Global', [{kind: 'globalobj'}], globalUrl); } - + // index page displays information from package.json and lists files var files = find({kind: 'file'}), packages = find({kind: 'package'}); @@ -454,14 +454,14 @@ exports.publish = function(taffyData, opts, tutorials) { var namespaces = taffy(members.namespaces); var mixins = taffy(members.mixins); var externals = taffy(members.externals); - + for (var longname in helper.longnameToUrl) { if ( hasOwnProp.call(helper.longnameToUrl, longname) ) { var myClasses = helper.find(classes, {longname: longname}); if (myClasses.length) { generate('Class: ' + myClasses[0].name, myClasses, helper.longnameToUrl[longname]); } - + var myModules = helper.find(modules, {longname: longname}); if (myModules.length) { generate('Module: ' + myModules[0].name, myModules, helper.longnameToUrl[longname]); @@ -471,7 +471,7 @@ exports.publish = function(taffyData, opts, tutorials) { if (myNamespaces.length) { generate('Namespace: ' + myNamespaces[0].name, myNamespaces, helper.longnameToUrl[longname]); } - + var myMixins = helper.find(mixins, {longname: longname}); if (myMixins.length) { generate('Mixin: ' + myMixins[0].name, myMixins, helper.longnameToUrl[longname]); @@ -492,16 +492,16 @@ exports.publish = function(taffyData, opts, tutorials) { content: tutorial.parse(), children: tutorial.children }; - + var tutorialPath = path.join(outdir, filename), html = view.render('tutorial.tmpl', tutorialData); - + // yes, you can use {@link} in tutorials too! html = helper.resolveLinks(html); // turn {@link foo} into foo - + fs.writeFileSync(tutorialPath, html, 'utf8'); } - + // tutorials can have only one parent so there is no risk for loops function saveChildren(node) { node.children.forEach(function(child) { diff --git a/config/jsdoc/info/publish.js b/config/jsdoc/info/publish.js index 5e1e2e0e2e..f429b678c8 100644 --- a/config/jsdoc/info/publish.js +++ b/config/jsdoc/info/publish.js @@ -6,11 +6,14 @@ var assert = require('assert'); var fs = require('fs'); var path = require('path'); +var Promise = require('bluebird'); + /** * Publish hook for the JSDoc template. Writes to JSON stdout. * @param {function} data The root of the Taffy DB containing doclet records. * @param {Object} opts Options. + * @return {Promise} A promise that resolves when writing is complete. */ exports.publish = function(data, opts) { @@ -168,13 +171,17 @@ exports.publish = function(data, opts) { return (symbol.name in augments || symbol.virtual); }); - process.stdout.write( - JSON.stringify({ - symbols: symbols, - defines: defines, - typedefs: typedefs, - externs: externs, - base: base - }, null, 2)); + return new Promise(function(resolve, reject) { + + process.stdout.write( + JSON.stringify({ + symbols: symbols, + defines: defines, + typedefs: typedefs, + externs: externs, + base: base + }, null, 2), resolve); + + }); }; diff --git a/package.json b/package.json index 20c1e81495..dac85ab194 100644 --- a/package.json +++ b/package.json @@ -26,14 +26,15 @@ }, "dependencies": { "async": "0.9.0", + "bluebird": "^2.10.1", "browserify": "9.0.3", - "derequire": "2.0.2", "closure-util": "1.8.0", + "derequire": "2.0.2", "fs-extra": "0.12.0", "glob": "5.0.3", "graceful-fs": "3.0.2", "handlebars": "3.0.1", - "jsdoc": "3.3.2", + "jsdoc-fork": "^4.0.0-beta.1", "marked": "0.3.5", "metalsmith": "1.6.0", "metalsmith-templates": "0.7.0", @@ -66,8 +67,18 @@ }, "ext": [ "rbush", - {"module": "pbf", "browserify": true}, - {"module": "pixelworks", "browserify": true}, - {"module": "vector-tile", "name": "vectortile", "browserify": true} + { + "module": "pbf", + "browserify": true + }, + { + "module": "pixelworks", + "browserify": true + }, + { + "module": "vector-tile", + "name": "vectortile", + "browserify": true + } ] }