diff --git a/README.md b/README.md index 8cb8c36c..9e924b7c 100644 --- a/README.md +++ b/README.md @@ -16,16 +16,15 @@ Installation Download a copy of JSDoc 3 from the official Git Hub repository here: -To build the jar file that runs JSDoc 3, use the Apache ant build tool: +To test that jsdoc is working, change your working directory to the jsdoc folder +and run the following command: - cd jsdoc - ant + java -classpath js.jar org.mozilla.javascript.tools.shell.Main jsdoc.js -T + +If you are operating on a Mac OSX or *nix platform, you can shorten that command +to this: -This will create a file named `jsdoc.jar` in the project base directory. - -To test that the newly installed app is working, execute the following: - - java -jar jsdoc.jar --test + ./jsdoc -T Usage ----- @@ -33,17 +32,11 @@ Usage This example assumes that your working directory is the jsdoc application base directory: - java -jar jsdoc.jar yourSourceCodeFile.js + ./jsdoc yourSourceCodeFile.js For help regarding the supported commandline options use the --help option. - java -jar jsdoc.jar --help - -Included with JSDoc 3 is a bash shell script that can simplify the command line -usage slightly. For example: - - ./jsdoc --help - ./jsdoc yourSourceCodeFile.js + ./jsdoc --help Dependencies ------------ @@ -59,9 +52,6 @@ configured to override that included Rhino and point to some older version of Rhino instead. If this is the case, simply correct the CLASSPATH to remove the older Rhino. -The build script for JSDoc 3 requires Apache ant. It is know to work with -version 1.8.2 of ant. - Debugging --------- @@ -70,8 +60,8 @@ JavaScript. Luckily it comes with a full-on debugger included that can be much more useful than a simple stack trace. To invoke JSDoc with the debugger try the following command: - $ java -classpath build-files/java/classes/js.jar \ - org.mozilla.javascript.tools.debugger.Main main.js `pwd` \ + $ java -classpath js.jar \ + org.mozilla.javascript.tools.debugger.Main jsdoc.js \ your/script.js This will open a debugging window. Choose "Break on Exceptions" from the "Debug" diff --git a/build-files/build.properties b/build-files/build.properties deleted file mode 100644 index ecaaae15..00000000 --- a/build-files/build.properties +++ /dev/null @@ -1,2 +0,0 @@ -app.name=jsdoc -app.version=3.0.0beta1 diff --git a/build-files/java/classes/js.jar b/build-files/java/classes/js.jar deleted file mode 100644 index 64d9e3af..00000000 Binary files a/build-files/java/classes/js.jar and /dev/null differ diff --git a/build-files/java/classes/sqlitejdbc-v054.jar b/build-files/java/classes/sqlitejdbc-v054.jar deleted file mode 100644 index 180de267..00000000 Binary files a/build-files/java/classes/sqlitejdbc-v054.jar and /dev/null differ diff --git a/build-files/java/src/Run.java b/build-files/java/src/Run.java deleted file mode 100644 index 37222cfb..00000000 --- a/build-files/java/src/Run.java +++ /dev/null @@ -1,56 +0,0 @@ -/* - OVERVIEW: - A bootstrap tool for running main.js. Assumes main.js is in - the same directory as the run.jar file. - - Its duty is simply to add the absolute path for main.js as - the first argument to the main.js script itself. This enables - the script to know it's own directory, useful for accessing - resources via relative filepaths. - - AUTHOR: Michael Mathews - LICENSE: Apache License 2.0 - See file 'LICENSE.md' in this project. - USAGE: java -jar run.jar - */ - -import java.io.File; -import java.net.URL; -import java.util.*; - -public class Run { - // requires java.io.File, java.net.URL - public static void main(String[] args) throws java.io.IOException { - - // get the absolute file path to the jar file containing this class - ClassLoader loader = Run.class.getClassLoader(); - - // url is like "file:/Users/michael/WorkArea/jsdoc/run.jar!/Run.class" - String jarUrl = loader.getResource("Run.class").getPath(); - - // parse the filepath out of the URL - String delims = "[:!]"; - String[] tokens = jarUrl.split(delims); - String jarPath = tokens[1]; - - // the base directory, assumed to contain main.js - String jarDir = new File(jarPath).getParent(); - String mainPath = jarDir + "/main.js"; - - // Rhino eats the first arg (the path to the script file it is running) - // so we add it twice: one for Rhino the next for us - String[] mainArgs = {mainPath, mainPath}; - String[] allArgs = concat(mainArgs, args); - - // main.js will now get arguments like: - // ["/abs/path/to/main.js", "-a", "aval", "-b", "bval"] - org.mozilla.javascript.tools.shell.Main.main(allArgs); - } - - // requires java.util - public static String[] concat(String[] a, String[] b) { - List ab = new ArrayList(a.length + b.length); - Collections.addAll(ab, a); - Collections.addAll(ab, b); - return ab.toArray(new String[] {}); - } -} diff --git a/build-files/templates/package.json b/build-files/templates/package.json deleted file mode 100644 index 3a39d8d9..00000000 --- a/build-files/templates/package.json +++ /dev/null @@ -1,36 +0,0 @@ -{ - "name": "@app.name@", - "version": "@app.version@", - "revision": "@timestamp@", - "description": "An automatic documentation generator for javascript.", - "keywords": [ "documentation", "javascript" ], - "licenses": [ - { - "type": "Apache 2.0", - "url": "http://www.apache.org/licenses/LICENSE-2.0" - } - ], - "repositories": [ - { - "type": "git", - "url": "git://github.com/micmath/jsdoc.git" - }, - { - "type": "svn", - "url": "https://jsdoc.googlecode.com/svn/trunk" - } - ], - "bugs": "http://code.google.com/p/jsdoc/issues/list", - "contributors" : [ - { - "name": "Michael Mathews", - "email": "micmath@gmail.com" - } - ], - "maintainers": [ - { - "name": "Michael Mathews", - "email": "micmath@gmail.com" - } - ] -} diff --git a/build.xml b/build.xml deleted file mode 100644 index 7e2edd03..00000000 --- a/build.xml +++ /dev/null @@ -1,71 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/jsdoc b/jsdoc index 0ccd48d0..7450ebc1 100755 --- a/jsdoc +++ b/jsdoc @@ -1,7 +1,4 @@ #!/bin/sh -BASEDIR=`dirname $0` -java -classpath ${BASEDIR}/build-files/java/classes/js.jar -jar ${BASEDIR}/jsdoc.jar $@ - -# or possibly? -# java -classpath build-files/java/classes/js.jar org.mozilla.javascript.tools.shell.Main main.js `pwd` \ No newline at end of file +#BASEDIR=`dirname $0` +java -classpath js.jar org.mozilla.javascript.tools.shell.Main jsdoc.js $@ diff --git a/main.js b/main.js deleted file mode 100644 index a837c8f3..00000000 --- a/main.js +++ /dev/null @@ -1,273 +0,0 @@ -/** - * @project jsdoc - * @author Michael Mathews - * @license See LICENSE.md file included in this distribution. - */ - -// try: $ java -classpath build-files/java/classes/js.jar org.mozilla.javascript.tools.shell.Main main.js `pwd` script/to/parse.js - -//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~// - -/** The absolute path to the base directory of the jsdoc application. - @type string - @global - */ -const BASEDIR = (arguments[0].replace(/([\/\\])main\.js$/, '$1') + '/').replace('//', '/'); // expects argument[0] to the abspath to main.js - -/** Include a JavaScript module, defined in the CommonJS way. - @param {string} id The identifier of the module you require. - @returns {mixed} The module's "exports" value. - @see - */ -function require(id) { // like commonjs - var moduleContent = '', - moduleUri; - - for (var i = 0, len = require.paths.length; i < len; i++) { - moduleUri = require.paths[i] + '/' + id + '.js'; - moduleContent = ''; - - var file = new java.io.File(moduleUri); - if ( file.exists() && file.canRead() && !file.isDirectory() ) { - try { - var scanner = new java.util.Scanner(file).useDelimiter("\\Z"); - moduleContent = String( scanner.next() ); - } - catch(ignored) { } - - if (moduleContent) { break; } - } - } - - if (moduleContent) { - try { - var f = new Function('require', 'exports', 'module', moduleContent), - exports = require.cache[moduleUri] || {}, - module = { id: id, uri: moduleUri }; - - - f.call({}, require, exports, module); - } - catch(e) { - throw 'Unable to require source code from "' + moduleUri + '": ' + e.toSource(); - } - - exports = module.exports || exports; - require.cache[id] = exports; - } - else { - throw 'The requested module cannot be returned: no content for id: "' + id + '" in paths: ' + require.paths.join(', '); - } - - return exports; -} -require.root = BASEDIR; -require.paths = [ require.root + 'modules', require.root + 'modules/common' ]; -require.cache = {}; // cache module exports. Like: {id: exported} - - -//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~// - - -/** Data representing the environment in which this app is running. - @namespace -*/ -env = { - /** Running start and finish times. */ - run: { - start: new Date(), - finish: null - }, - - /** - The command line arguments passed into jsdoc. - @type Array - */ - args: Array.prototype.slice.call(arguments, 1), // jsdoc.jar adds argument[0], the abspath to main.js, user args follow - - - /** - The parsed JSON data from the configuration file. - @type Object - */ - conf: {}, - - /** - The command line arguments, parsed into a key/value hash. - @type Object - @example if (env.opts.help) { print 'Helpful message.'; } - */ - opts: {} -}; - -/** - Data that must be shared across the entire application. - @namespace -*/ -app = { - jsdoc: { - scanner: new (require('jsdoc/src/scanner').Scanner)(), - parser: new (require('jsdoc/src/parser').Parser)(), - name: require('jsdoc/name') - } -} - -try { main(); } -catch(e) { - if (e.rhinoException != null) { - e.rhinoException.printStackTrace(); - } - else throw e; -} -finally { env.run.finish = new Date(); } - -/** Print string/s out to the console. - @param {string} ... String/s to print out to console. - */ -function print() { - for (var i = 0, leni = arguments.length; i < leni; i++) { - java.lang.System.out.println('' + arguments[i]); - } -} - -/** - Try to recursively print out all key/values in an object. - @global - @param {Object} ... Object/s to dump out to console. - */ -function dump() { - for (var i = 0, leni = arguments.length; i < leni; i++) { - print( require('common/dumper').dump(arguments[i]) ); - } -} - -/** @global - @param {string} filepath The path to the script file to include (read and execute). -*/ -function include(filepath) { - try { - load(BASEDIR + filepath); - } - catch (e) { - print('Cannot include "' + BASEDIR + filepath + '": '+e); - } -} - -/** - Cause the VM running jsdoc to exit running. - @param {number} [n = 0] The exit status. - */ -function exit(n) { - n = n || 0; - java.lang.System.exit(n); -} - - -//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~// - - -/** - Run the jsoc application. - */ -function main() { - var sourceFiles, - packageJson, - docs, - jsdoc = { - opts: { - parser: require('jsdoc/opts/parser'), - } - }; - - env.opts = jsdoc.opts.parser.parse(env.args); - - try { - env.conf = JSON.parse( - require('fs').read( env.opts.configure || BASEDIR+'conf.json' ) - ); - } - catch (e) { - throw('Configuration file cannot be evaluated. '+e); - } - - if (env.opts.query) { - env.opts.query = require('query').toObject(env.opts.query); - } - - if (env.opts.help) { - print( jsdoc.opts.parser.help() ); - exit(0); - } - else if (env.opts.test) { - include('test/runner.js'); - exit(0); - } - - // allow user-defined plugins to register listeners - if (env.conf.plugins) { - for (var i = 0, leni = env.conf.plugins.length; i < leni; i++) { - include(env.conf.plugins[i]); - } - } - - // any source file named package.json is treated special - for (var i = 0, l = env.opts._.length; i < l; i++ ) { - if (/\bpackage\.json$/i.test(env.opts._[i])) { - packageJson = require('fs').read( env.opts._[i] ); - env.opts._.splice(i--, 1); - } - } - - if (env.opts._.length > 0) { // are there any files to scan and parse? - - var includeMatch = (env.conf.source && env.conf.source.includePattern)? new RegExp(env.conf.source.includePattern) : null, - excludeMatch = (env.conf.source && env.conf.source.excludePattern)? new RegExp(env.conf.source.excludePattern) : null; - - sourceFiles = app.jsdoc.scanner.scan(env.opts._, (env.opts.recurse? 10 : undefined), includeMatch, excludeMatch); - - require('jsdoc/src/handlers').attachTo(app.jsdoc.parser); - - docs = app.jsdoc.parser.parse(sourceFiles, env.opts.encoding); - - if (packageJson) { - var packageDocs = new (require('jsdoc/package').Package)(packageJson); - packageDocs.files = sourceFiles || []; - docs.push(packageDocs); - } - - function indexAll(docs) { - var lookupTable = {}; - - docs.forEach(function(doc) { - if ( !lookupTable.hasOwnProperty(doc.longname) ) { - lookupTable[doc.longname] = []; - } - lookupTable[doc.longname].push(doc); - }); - docs.index = lookupTable; - } - - indexAll(docs); - - require('jsdoc/borrow').resolveBorrows(docs); - - if (env.opts.expel) { - dump(docs); - exit(0); - } - - env.opts.template = env.opts.template || 'default'; - - // should define a global "publish" function - include('templates/' + env.opts.template + '/publish.js'); - - if (typeof publish === 'function') { - publish( - new (require('typicaljoe/taffy'))(docs), - env.opts - ); - } - else { // TODO throw no publish warning? - } - } -} \ No newline at end of file