From 6d3bbe61ce5cee95e6304e55e1d4c9a2908aa61e Mon Sep 17 00:00:00 2001 From: Paul Spencer Date: Mon, 7 Apr 2014 19:18:02 -0400 Subject: [PATCH] Upgrade to jsdoc 3.3. --- .travis.yml | 7 +-- apidoc/conf.json | 2 +- apidoc/plugins/inheritdoc.js | 2 +- apidoc/template/publish.js | 94 ++++++++++++++++++------------------ build.py | 4 +- package.json | 3 +- 6 files changed, 54 insertions(+), 58 deletions(-) diff --git a/.travis.yml b/.travis.yml index ab29d9bd3a..7a11387ca0 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,10 +1,5 @@ before_install: - "sudo pip install -r requirements.txt" - - "git clone --depth=50 https://github.com/jsdoc3/jsdoc build/jsdoc" - - "cd build/jsdoc" - - "git fetch origin refs/tags/v3.2.2:refs/tags/v3.2.2" - - "git checkout tags/v3.2.2" - - "cd ../.." - "npm install" before_script: @@ -13,4 +8,4 @@ before_script: - "rm src/ol/renderer/webgl/*shader.js" - "sleep 3" -script: "./build.py JSDOC=build/jsdoc/jsdoc integration-test" +script: "./build.py integration-test" diff --git a/apidoc/conf.json b/apidoc/conf.json index 8131a4bc6e..0aa799c414 100644 --- a/apidoc/conf.json +++ b/apidoc/conf.json @@ -17,7 +17,7 @@ ] }, "plugins": [ - "plugins/markdown", + "node_modules/jsdoc/plugins/markdown", "apidoc/plugins/inheritdoc", "apidoc/plugins/exports", "apidoc/plugins/todo", diff --git a/apidoc/plugins/inheritdoc.js b/apidoc/plugins/inheritdoc.js index 4c2f571844..673017b702 100644 --- a/apidoc/plugins/inheritdoc.js +++ b/apidoc/plugins/inheritdoc.js @@ -5,7 +5,7 @@ * TODO: Remove this hack when https://github.com/jsdoc3/jsdoc/issues/53 * is addressed. */ -exports.nodeVisitor = { +exports.astNodeVisitor = { visitNode: function(node, e, parser, currentSourceName) { if (/@(inheritDoc)(\n|\r)/.test(e.comment)) { diff --git a/apidoc/template/publish.js b/apidoc/template/publish.js index cb26529918..ebdf4920eb 100644 --- a/apidoc/template/publish.js +++ b/apidoc/template/publish.js @@ -1,7 +1,7 @@ /*global env: true */ var template = require('jsdoc/template'), - fs = require('fs'), - path = require('path'), + fs = require('jsdoc/fs'), + path = require('jsdoc/path'), taffy = require('taffydb').taffy, helper = require('jsdoc/util/templateHelper'), scopeToPunc = helper.scopeToPunc, @@ -29,48 +29,48 @@ var htmlsafe = helper.htmlsafe; function hashToLink(doclet, hash) { if ( !/^(#.+)/.test(hash) ) { return hash; } - + var url = helper.createLink(doclet); - + url = url.replace(/(#.+|$)/, hash); return '' + hash + ''; } 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 || '') + '' + ''+(returnTypes.length? ' → {'+returnTypes.join('|')+'}' : '')+''; } function addSignatureTypes(f) { var types = helper.getSignatureTypes(f); - + f.signature = (f.signature || '') + ''+(types.length? ' :'+types.join('|') : '')+''; } function addAttribs(f) { var attribs = helper.getAttribs(f); - + f.attribs = ''+htmlsafe(attribs.length? '<'+attribs.join(', ')+'> ' : '')+''; } - + function generate(title, docs, filename) { var docData = { title: title, docs: docs }; - + var outpath = path.join(outdir, filename), html = view.render('container.tmpl', docData); - + html = helper.resolveLinks(html); // turn {@link foo} into foo - + fs.writeFileSync(outpath, html, 'utf8'); } @@ -89,7 +89,7 @@ function generate(title, docs, filename) { function buildNav(members) { var nav = '

Index

', seen = {}; - + /** * Sorts elements by their qualified names (property longname). * See https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array/sort @@ -115,10 +115,10 @@ function buildNav(members) { } seen[m.longname] = true; }); - + nav += ''; } - + if (members.externals.length) { nav += '

Externals

'; } @@ -149,10 +149,10 @@ function buildNav(members) { } seen[c.longname] = true; }); - + nav += ''; } - + if (members.namespaces.length) { nav += '

Namespaces

'; } - + if (members.mixins.length) { nav += '

Mixins

'; } @@ -182,10 +182,10 @@ function buildNav(members) { members.tutorials.sort(byLongName).forEach(function(t) { nav += '
  • '+tutoriallink(t.name)+'
    • '; }); - + nav += ''; } - + if (members.globals.length) { nav += '

    Global

    '; } @@ -212,7 +212,7 @@ exports.publish = function(taffyData, opts, tutorials) { var templatePath = opts.template; view = new template.Template(templatePath + '/tmpl'); - + // set up templating view.layout = 'layout.tmpl'; @@ -224,16 +224,16 @@ exports.publish = function(taffyData, opts, tutorials) { 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 @@ -246,7 +246,7 @@ exports.publish = function(taffyData, opts, tutorials) { }); } }); - + // update outdir if necessary, then create outdir var packageInfo = ( find({kind: 'package'}) || [] ) [0]; if (packageInfo && packageInfo.name) { @@ -257,18 +257,18 @@ exports.publish = function(taffyData, opts, tutorials) { // copy static files to outdir var fromDir = path.join(templatePath, 'static'), staticFiles = fs.ls(fromDir, 3); - + staticFiles.forEach(function(fileName) { var toDir = fs.toDir( fileName.replace(fromDir, outdir) ); fs.mkPath(toDir); fs.copyFileSync(fileName, toDir); }); - + data().each(function(doclet) { var url = helper.createLink(doclet); helper.registerLink(doclet.longname, url); }); - + data().each(function(doclet) { var url = helper.longnameToUrl[doclet.longname]; @@ -278,32 +278,32 @@ exports.publish = function(taffyData, opts, tutorials) { else { doclet.id = doclet.name; } - + if (doclet.kind === 'function' || doclet.kind === 'class') { addSignatureParams(doclet); addSignatureReturns(doclet); addAttribs(doclet); } }); - + // do this after the urls have all been generated data().each(function(doclet) { doclet.ancestors = getAncestorLinks(doclet); doclet.signature = ''; - + if (doclet.kind === 'member') { addSignatureTypes(doclet); addAttribs(doclet); } - + if (doclet.kind === 'constant') { addSignatureTypes(doclet); addAttribs(doclet); doclet.kind = 'member'; } }); - + var members = helper.getMembers(data); members.tutorials = tutorials.children; @@ -324,25 +324,25 @@ exports.publish = function(taffyData, opts, tutorials) { if (classes.length) { generate('Class: ' + classes[0].longname, classes, helper.longnameToUrl[longname]); } - + var modules = taffy(members.modules); modules = helper.find(modules, {longname: longname}); if (modules.length) { generate('Module: ' + modules[0].longname, modules, helper.longnameToUrl[longname]); } - + var namespaces = taffy(members.namespaces); namespaces = helper.find(namespaces, {longname: longname}); if (namespaces.length) { generate('Namespace: ' + namespaces[0].longname, namespaces, helper.longnameToUrl[longname]); } - + var mixins = taffy(members.mixins); mixins = helper.find(mixins, {longname: longname}); if (mixins.length) { generate('Mixin: ' + mixins[0].longname, mixins, helper.longnameToUrl[longname]); } - + var externals = taffy(members.externals); externals = helper.find(externals, {longname: longname}); if (externals.length) { @@ -352,7 +352,7 @@ exports.publish = function(taffyData, opts, tutorials) { } if (members.globals.length) { generate('Global', members.globals, 'global.html'); } - + // index page displays information from package.json and lists files var files = find({kind: 'file'}), packages = find({kind: 'package'}); @@ -362,7 +362,7 @@ exports.publish = function(taffyData, opts, tutorials) { [{kind: 'mainpage', readme: opts.readme, longname: (opts.mainpagetitle) ? opts.mainpagetitle : 'Main Page'}] ).concat(files), 'index.html'); - + // TODO: move the tutorial functions to templateHelper.js function generateTutorial(title, tutorial, filename) { var tutorialData = { @@ -371,16 +371,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/build.py b/build.py index 8045b1a83e..1133732ba6 100755 --- a/build.py +++ b/build.py @@ -20,7 +20,7 @@ if sys.platform == 'win32': 'GJSLINT': 'gjslint.exe', 'JAVA': 'java.exe', 'JAR': 'jar.exe', - 'JSDOC': 'jsdoc.cmd', + 'JSDOC': './node_modules/.bin/jsdoc', 'JSHINT': './node_modules/.bin/jshint', 'PYTHON': 'python.exe', 'PHANTOMJS': 'phantomjs.cmd' @@ -75,7 +75,7 @@ else: variables.JSHINT = './node_modules/.bin/jshint' variables.JAVA = 'java' variables.JAR = 'jar' - variables.JSDOC = 'jsdoc' + variables.JSDOC = './node_modules/.bin/jsdoc' variables.PYTHON = 'python' variables.PHANTOMJS = 'phantomjs' diff --git a/package.json b/package.json index 3c8f7b8561..3e5d7556b6 100644 --- a/package.json +++ b/package.json @@ -18,6 +18,7 @@ "closure-util": "~0.9.0", "async": "~0.2.10", "htmlparser2": "~3.7.1", - "jshint": "~2.4.4" + "jshint": "~2.4.4", + "jsdoc": "^3.3.0-alpha5" } }