Removing my own jar file and just including rhino with updated instructions on how to run jsdoc via rhino directly, build script is no longer necessary. This should path issues reported on non *nix platforms. [closes #15]

This commit is contained in:
Michael Mathews 2011-05-10 21:03:37 +01:00
parent a43ca23c24
commit ee382cdad1
9 changed files with 13 additions and 464 deletions

View File

@ -16,16 +16,15 @@ Installation
Download a copy of JSDoc 3 from the official Git Hub repository here: Download a copy of JSDoc 3 from the official Git Hub repository here:
<https://github.com/micmath/jsdoc> <https://github.com/micmath/jsdoc>
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 java -classpath js.jar org.mozilla.javascript.tools.shell.Main jsdoc.js -T
ant
This will create a file named `jsdoc.jar` in the project base directory. If you are operating on a Mac OSX or *nix platform, you can shorten that command
to this:
To test that the newly installed app is working, execute the following: ./jsdoc -T
java -jar jsdoc.jar --test
Usage Usage
----- -----
@ -33,17 +32,11 @@ Usage
This example assumes that your working directory is the jsdoc application base This example assumes that your working directory is the jsdoc application base
directory: directory:
java -jar jsdoc.jar yourSourceCodeFile.js ./jsdoc yourSourceCodeFile.js
For help regarding the supported commandline options use the --help option. 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 --help
./jsdoc yourSourceCodeFile.js
Dependencies 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 Rhino instead. If this is the case, simply correct the CLASSPATH to remove the
older Rhino. older Rhino.
The build script for JSDoc 3 requires Apache ant. It is know to work with
version 1.8.2 of ant.
Debugging 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 more useful than a simple stack trace. To invoke JSDoc with the debugger try the
following command: following command:
$ java -classpath build-files/java/classes/js.jar \ $ java -classpath js.jar \
org.mozilla.javascript.tools.debugger.Main main.js `pwd` \ org.mozilla.javascript.tools.debugger.Main jsdoc.js \
your/script.js your/script.js
This will open a debugging window. Choose "Break on Exceptions" from the "Debug" This will open a debugging window. Choose "Break on Exceptions" from the "Debug"

View File

@ -1,2 +0,0 @@
app.name=jsdoc
app.version=3.0.0beta1

Binary file not shown.

View File

@ -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 <micmath@gmail.com>
LICENSE: Apache License 2.0 - See file 'LICENSE.md' in this project.
USAGE: java -jar run.jar <args>
*/
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<String> ab = new ArrayList<String>(a.length + b.length);
Collections.addAll(ab, a);
Collections.addAll(ab, b);
return ab.toArray(new String[] {});
}
}

View File

@ -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"
}
]
}

View File

@ -1,71 +0,0 @@
<?xml version="1.0"?>
<project name="jsdoc" default="jar-install">
<property file="build-files/build.properties" />
<property name="build.templates" location="build-files/templates" />
<tstamp>
<format property="NOW" pattern="yyyy-MM-dd-HHmm" locale="en,UK"/>
</tstamp>
<!-- build the package.json file -->
<target name="about">
<delete file="package.json" quiet="true"/>
<copy file="${build.templates}/package.json" tofile="package.json" >
<filterchain>
<replacetokens>
<token key="app.name" value="${app.name}" />
<token key="app.version" value="${app.version}" />
<token key="timestamp" value="${NOW}" />
</replacetokens>
</filterchain>
</copy>
</target>
<!-- commit a copy of master to subversion -->
<target name="mirror">
<exec executable="/usr/local/git/bin/git">
<arg value="svn" />
<arg value="dcommit" />
</exec>
</target>
<!-- steps to build and install the jsdoc.jar file: clean, compile, build -->
<target name="jar-clean">
<delete dir="build-files/java/build" />
<delete file="jsdoc.jar" />
</target>
<target name="jar-compile">
<path id="local-classes">
<fileset dir="build-files/java/classes/">
<include name="*.jar" />
</fileset>
</path>
<mkdir dir="build-files/java/build/classes" />
<javac srcdir="build-files/java/src"
destdir="build-files/java/build/classes"
includeAntRuntime="false">
<classpath refid="local-classes" />
</javac>
</target>
<target name="jar-build" depends="jar-compile">
<mkdir dir="build-files/java/build/jar" />
<jar destfile="build-files/java/build/jar/jsdoc.jar" basedir="build-files/java/build/classes">
<manifest>
<attribute name="Main-Class" value="Run" />
<attribute name="Class-Path" value="build-files/java/classes/js.jar build-files/java/classes/sqlitejdbc-v054.jar" />
</manifest>
</jar>
</target>
<!-- do all the steps to build and install the jsdoc.jar file -->
<target name="jar-install" depends="jar-clean, jar-build">
<copy file="build-files/java/build/jar/jsdoc.jar" tofile="jsdoc.jar" overwrite="true" />
</target>
</project>

7
jsdoc
View File

@ -1,7 +1,4 @@
#!/bin/sh #!/bin/sh
BASEDIR=`dirname $0` #BASEDIR=`dirname $0`
java -classpath ${BASEDIR}/build-files/java/classes/js.jar -jar ${BASEDIR}/jsdoc.jar $@ java -classpath js.jar org.mozilla.javascript.tools.shell.Main jsdoc.js $@
# or possibly?
# java -classpath build-files/java/classes/js.jar org.mozilla.javascript.tools.shell.Main main.js `pwd`

273
main.js
View File

@ -1,273 +0,0 @@
/**
* @project jsdoc
* @author Michael Mathews <micmath@gmail.com>
* @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 <http://wiki.commonjs.org/wiki/Modules/1.1>
*/
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?
}
}
}