jsdoc-toolkit 0.1.1 → 0.1.2

data/src/jsdoc-toolkit/jsdoc-toolkit/app/main.js

@@ -0,0 +1,111 @@
+/**
+ * @version $Id$
+ */
+
+function main() {
+	IO.include("lib/JSDOC.js");
+	IO.includeDir("plugins/");
+	
+	// process the options
+	
+	// the -c option: options are defined in a configuration file
+	if (JSDOC.opt.c) {
+		eval("JSDOC.conf = " + IO.readFile(JSDOC.opt.c));
+		
+		LOG.inform("Using configuration file at '"+JSDOC.opt.c+"'.");
+		
+		for (var c in JSDOC.conf) {
+			if (c !== "D" && !defined(JSDOC.opt[c])) { // commandline overrules config file
+				JSDOC.opt[c] = JSDOC.conf[c];
+			}
+		}
+		
+		if (typeof JSDOC.conf["_"] != "undefined") {
+			JSDOC.opt["_"] = JSDOC.opt["_"].concat(JSDOC.conf["_"]);
+		}
+		
+		LOG.inform("With configuration: ");
+		for (var o in JSDOC.opt) {
+			LOG.inform("    "+o+": "+JSDOC.opt[o]);
+		}
+	}
+	
+	// be verbose
+	if (JSDOC.opt.v) LOG.verbose = true;
+	
+	// send log messages to a file
+	if (JSDOC.opt.o) LOG.out = IO.open(JSDOC.opt.o);
+	
+	// run the unit tests
+	if (JSDOC.opt.T) {
+		LOG.inform("JsDoc Toolkit running in test mode at "+new Date()+".");
+		IO.include("frame/Testrun.js");
+		IO.include("test.js");
+	}
+	else {
+		// a template must be defined and must be a directory path
+		if (!JSDOC.opt.t && System.getProperty("jsdoc.template.dir")) {
+			JSDOC.opt.t = System.getProperty("jsdoc.template.dir");
+		}
+		if (JSDOC.opt.t && !JSDOC.opt.t.charAt(JSDOC.opt.t.length-1).match(/[\\\/]/)) {
+			JSDOC.opt.t += SYS.slash;
+		}
+		
+		// verbose messages about the options we were given
+		LOG.inform("JsDoc Toolkit main() running at "+new Date()+".");
+		LOG.inform("With options: ");
+		for (var o in JSDOC.opt) {
+			LOG.inform("    "+o+": "+JSDOC.opt[o]);
+		}
+		
+		// initialize and build a symbolSet from your code
+		JSDOC.JsDoc();
+		
+		// debugger's option: dump the entire symbolSet produced from your code
+		if (JSDOC.opt.Z) {
+			LOG.warn("So you want to see the data structure, eh? This might hang if you have circular refs...");
+			IO.include("frame/Dumper.js");
+			var symbols = JSDOC.JsDoc.symbolSet.toArray();
+			for (var i = 0, l = symbols.length; i < l; i++) {
+				var symbol = symbols[i];
+				print("// symbol: " + symbol.alias);
+				print(symbol.serialize());
+			}
+		}
+		else {
+			if (typeof JSDOC.opt.t != "undefined") {
+				try {
+					// a file named "publish.js" must exist in the template directory
+					load(JSDOC.opt.t+"publish.js");
+					
+					// and must define a function named "publish"
+					if (!publish) {
+						LOG.warn("No publish() function is defined in that template so nothing to do.");
+					}
+					else {
+						// which will be called with the symbolSet produced from your code
+						publish(JSDOC.JsDoc.symbolSet);
+					}
+				}
+				catch(e) {
+					LOG.warn("Sorry, that doesn't seem to be a valid template: "+JSDOC.opt.t+"publish.js : "+e);
+				}
+			}
+			else {
+				LOG.warn("No template given. Might as well read the usage notes.");
+				JSDOC.usage();
+			}
+		}
+	}
+	
+	// notify of any warnings
+	if (!JSDOC.opt.q && LOG.warnings.length) {
+		print(LOG.warnings.length+" warning"+(LOG.warnings.length != 1? "s":"")+".");
+	}
+	
+	// stop sending log messages to a file
+	if (LOG.out) {
+		LOG.out.flush();
+		LOG.out.close();
+	}
+}

data/src/jsdoc-toolkit/jsdoc-toolkit/app/plugins/commentSrcJson.js

@@ -0,0 +1,20 @@
+JSDOC.PluginManager.registerPlugin(
+	"JSDOC.commentSrcJson",
+	{
+		onDocCommentSrc: function(comment) {
+			var json;
+			if (/^\s*@json\b/.test(comment)) {
+				comment.src = new String(comment.src).replace("@json", "");
+
+				eval("json = "+comment.src);
+				var tagged = "";
+				for (var i in json) {
+					var tag = json[i];
+					// todo handle cases where tag is an object
+					tagged += "@"+i+" "+tag+"\n";
+				}
+				comment.src = tagged;
+			}
+		}
+	}
+);

data/src/jsdoc-toolkit/jsdoc-toolkit/app/plugins/frameworkPrototype.js

@@ -0,0 +1,16 @@
+JSDOC.PluginManager.registerPlugin(
+	"JSDOC.frameworkPrototype",
+	{
+		onPrototypeClassCreate: function(classCreator) {
+			var desc = "";
+			if (classCreator.comment) {
+				desc = classCreator.comment;
+			}
+			var insert = desc+"/** @name "+classCreator.name+"\n@constructor\n@scope "+classCreator.name+".prototype */"
+			
+			insert = insert.replace(/\*\/\/\*\*/g, "\n");
+			/*DEBUG*///print("insert is "+insert);
+			classCreator.addComment.data = insert;
+		}
+	}
+);

data/src/jsdoc-toolkit/jsdoc-toolkit/app/plugins/functionCall.js

@@ -0,0 +1,10 @@
+JSDOC.PluginManager.registerPlugin(
+	"JSDOC.functionCall",
+	{
+		onFunctionCall: function(functionCall) {
+			if (functionCall.name == "dojo.define" && functionCall.arg1) {
+				functionCall.doc = "/** @lends "+eval(functionCall.arg1)+".prototype */";
+			}
+		}
+	}
+);

data/src/jsdoc-toolkit/jsdoc-toolkit/app/plugins/publishSrcHilite.js

@@ -0,0 +1,62 @@
+JSDOC.PluginManager.registerPlugin(
+	"JSDOC.publishSrcHilite",
+	{
+		onPublishSrc: function(src) {
+			if (src.path in JsHilite.cache) {
+				return; // already generated src code
+			}
+			else JsHilite.cache[src.path] = true;
+		
+			try {
+				var sourceCode = IO.readFile(src.path);
+			}
+			catch(e) {
+				print(e.message);
+				quit();
+			}
+
+			var hiliter = new JsHilite(sourceCode, src.charset);
+			src.hilited = hiliter.hilite();
+		}
+	}
+);
+
+function JsHilite(src, charset) {
+
+	var tr = new JSDOC.TokenReader();
+	
+	tr.keepComments = true;
+	tr.keepDocs = true;
+	tr.keepWhite = true;
+	
+	this.tokens = tr.tokenize(new JSDOC.TextStream(src));
+	
+	// TODO is redefining toString() the best way?
+	JSDOC.Token.prototype.toString = function() { 
+		return "<span class=\""+this.type+"\">"+this.data.replace(/</g, "&lt;")+"</span>";
+	}
+	
+	if (!charset) charset = "utf-8";
+	
+	this.header = '<html><head><meta http-equiv="content-type" content="text/html; charset='+charset+'"> '+
+	"<style>\n\
+	.KEYW {color: #933;}\n\
+	.COMM {color: #bbb; font-style: italic;}\n\
+	.NUMB {color: #393;}\n\
+	.STRN {color: #393;}\n\
+	.REGX {color: #339;}\n\
+	.line {border-right: 1px dotted #666; color: #666; font-style: normal;}\n\
+	</style></head><body><pre>";
+	this.footer = "</pre></body></html>";
+	this.showLinenumbers = true;
+}
+
+JsHilite.cache = {};
+
+JsHilite.prototype.hilite = function() {
+	var hilited = this.tokens.join("");
+	var line = 1;
+	if (this.showLinenumbers) hilited = hilited.replace(/(^|\n)/g, function(m){return m+"<span class='line'>"+((line<10)? " ":"")+((line<100)? " ":"")+(line++)+"</span> "});
+	
+	return this.header+hilited+this.footer;
+}

data/src/jsdoc-toolkit/jsdoc-toolkit/app/plugins/symbolLink.js

@@ -0,0 +1,10 @@
+JSDOC.PluginManager.registerPlugin(
+	"JSDOC.symbolLink",
+	{
+		onSymbolLink: function(link) {
+			// modify link.linkPath (the href part of the link)
+			// or link.linkText (the text displayed)
+			// or link.linkInner (the #name part of the link)
+		}
+	}
+);

data/src/jsdoc-toolkit/jsdoc-toolkit/app/plugins/tagParamConfig.js

@@ -0,0 +1,31 @@
+JSDOC.PluginManager.registerPlugin(
+	"JSDOC.tagParamConfig",
+	{
+		onDocCommentTags: function(comment) {
+			var currentParam = null;
+			var tags = comment.tags;
+			for (var i = 0, l = tags.length; i < l; i++) {
+				
+				if (tags[i].title == "param") {
+					if (tags[i].name.indexOf(".") == -1) {
+						currentParam = i;
+					}
+				}
+				else if (tags[i].title == "config") {
+					tags[i].title = "param";
+					if (currentParam == null) {
+						tags[i].name = "arguments"+"."+tags[i].name;
+					}
+					else if (tags[i].name.indexOf(tags[currentParam].name+".") != 0) {
+						tags[i].name = tags[currentParam].name+"."+tags[i].name;
+					}
+					currentParam != null
+					//tags[currentParam].properties.push(tags[i]);
+				}
+				else {
+					currentParam = null;
+				}
+			}
+		}
+	}
+);

data/src/jsdoc-toolkit/jsdoc-toolkit/app/plugins/tagSynonyms.js

@@ -0,0 +1,43 @@
+JSDOC.PluginManager.registerPlugin(
+	"JSDOC.tagSynonyms",
+	{
+		onDocCommentSrc: function(comment) {
+			comment.src = comment.src.replace(/@methodOf\b/i, "@function\n@memberOf");
+			comment.src = comment.src.replace(/@fieldOf\b/i, "@field\n@memberOf");
+		},
+		
+		onDocCommentTags: function(comment) {
+			for (var i = 0, l = comment.tags.length; i < l; i++) {
+				var title = comment.tags[i].title.toLowerCase();
+				var syn;
+				if ((syn = JSDOC.tagSynonyms.synonyms["="+title])) {
+					comment.tags[i].title = syn;
+				}
+			}
+		}
+	}
+);
+
+new Namespace(
+	"JSDOC.tagSynonyms",
+	function() {
+		JSDOC.tagSynonyms.synonyms = {
+			"=member":             "memberOf",
+			"=memberof":           "memberOf",
+			"=description":        "desc",
+			"=exception":          "throws",
+			"=argument":           "param",
+			"=returns":            "return",
+			"=classdescription":   "class",
+			"=fileoverview":       "overview",
+			"=extends":            "augments",
+			"=base":               "augments",
+			"=projectdescription": "overview",
+			"=classdescription":   "class",
+			"=link":               "see",
+			"=borrows":            "inherits",
+			"=scope":              "lends",
+			"=construct":          "constructor"
+		}
+	}
+);

data/src/jsdoc-toolkit/jsdoc-toolkit/app/run.js

@@ -0,0 +1,348 @@
+/**
+ * @fileOverview
+ * A bootstrap script that creates some basic required objects
+ * for loading other scripts.
+ * @author Michael Mathews, micmath@gmail.com
+ * @version $Id$
+ */
+
+/**
+ * @namespace Keep track of any messages from the running script.
+ */
+LOG = {
+	warn: function(msg, e) {
+		if (JSDOC.opt.q) return;
+		if (e) msg = e.fileName+", line "+e.lineNumber+": "+msg;
+		
+		msg = ">> WARNING: "+msg;
+		LOG.warnings.push(msg);
+		if (LOG.out) LOG.out.write(msg+"\n");
+		else print(msg);
+	},
+
+	inform: function(msg) {
+		if (JSDOC.opt.q) return;
+		msg = " > "+msg;
+		if (LOG.out) LOG.out.write(msg+"\n");
+		else if (typeof LOG.verbose != "undefined" && LOG.verbose) print(msg);
+	}
+};
+LOG.warnings = [];
+LOG.verbose = false
+LOG.out = undefined;
+
+/**
+ *	@class Manipulate a filepath.
+ */
+function FilePath(absPath, separator) {
+	this.slash =  separator || "/"; 
+	this.root = this.slash;
+	this.path = [];
+	this.file = "";
+	
+	var parts = absPath.split(/[\\\/]/);
+	if (parts) {
+		if (parts.length) this.root = parts.shift() + this.slash;
+		if (parts.length) this.file =  parts.pop()
+		if (parts.length) this.path = parts;
+	}
+	
+	this.path = this.resolvePath();
+}
+
+/** Collapse any dot-dot or dot items in a filepath. */
+FilePath.prototype.resolvePath = function() {
+	var resolvedPath = [];
+	for (var i = 0; i < this.path.length; i++) {
+		if (this.path[i] == "..") resolvedPath.pop();
+		else if (this.path[i] != ".") resolvedPath.push(this.path[i]);
+	}
+	return resolvedPath;
+}
+
+/** Trim off the filename. */
+FilePath.prototype.toDir = function() {
+	if (this.file) this.file = "";
+	return this;
+}
+
+/** Go up a directory. */
+FilePath.prototype.upDir = function() {
+	this.toDir();
+	if (this.path.length) this.path.pop();
+	return this;
+}
+
+FilePath.prototype.toString = function() {
+	return this.root
+		+ this.path.join(this.slash)
+		+ ((this.path.length > 0)? this.slash : "")
+		+ this.file;
+}
+
+/**
+ * Turn a path into just the name of the file.
+ */
+FilePath.fileName = function(path) {
+	var nameStart = Math.max(path.lastIndexOf("/")+1, path.lastIndexOf("\\")+1, 0);
+	return path.substring(nameStart);
+}
+
+/**
+ * Get the extension of a filename
+ */
+FilePath.fileExtension = function(filename) {
+   return filename.split(".").pop().toLowerCase();
+};
+
+/**
+ * Turn a path into just the directory part.
+ */
+FilePath.dir = function(path) {
+	var nameStart = Math.max(path.lastIndexOf("/")+1, path.lastIndexOf("\\")+1, 0);
+	return path.substring(0, nameStart-1);
+}
+
+
+importClass(java.lang.System);
+
+/**
+ * @namespace A collection of information about your system.
+ */
+SYS = {
+	/**
+	 * Information about your operating system: arch, name, version.
+	 * @type string
+	 */
+	os: [
+		new String(System.getProperty("os.arch")),
+		new String(System.getProperty("os.name")),
+		new String(System.getProperty("os.version"))
+	].join(", "),
+	
+	/**
+	 * Which way does your slash lean.
+	 * @type string
+	 */
+	slash: System.getProperty("file.separator")||"/",
+	
+	/**
+	 * The path to the working directory where you ran java.
+	 * @type string
+	 */
+	userDir: new String(System.getProperty("user.dir")),
+	
+	/**
+	 * Where is Java's home folder.
+	 * @type string
+	 */
+	javaHome: new String(System.getProperty("java.home")),
+	
+	/**
+	 * The absolute path to the directory containing this script.
+	 * @type string
+	 */
+	pwd: undefined
+};
+
+// jsrun appends an argument, with the path to here.
+if (arguments[arguments.length-1].match(/^-j=(.+)/)) {
+	if (RegExp.$1.charAt(0) == SYS.slash || RegExp.$1.charAt(1) == ":") { // absolute path to here
+		SYS.pwd = new FilePath(RegExp.$1).toDir().toString();
+	}
+	else { // relative path to here
+		SYS.pwd = new FilePath(SYS.userDir + SYS.slash + RegExp.$1).toDir().toString();
+	}
+	arguments.pop();
+}
+else {
+	print("The run.js script requires you use jsrun.jar.");
+	quit();
+}
+
+// shortcut
+var File = Packages.java.io.File;
+
+/**
+ * @namespace A collection of functions that deal with reading a writing to disk.
+ */
+IO = {
+
+	/**
+	 * Create a new file in the given directory, with the given name and contents.
+	 */
+	saveFile: function(/**string*/ outDir, /**string*/ fileName, /**string*/ content) {
+		var out = new Packages.java.io.PrintWriter(
+			new Packages.java.io.OutputStreamWriter(
+				new Packages.java.io.FileOutputStream(outDir+SYS.slash+fileName),
+				IO.encoding
+			)
+		);
+		out.write(content);
+		out.flush();
+		out.close();
+	},
+	
+	/**
+	 * @type string
+	 */
+	readFile: function(/**string*/ path) {
+		if (!IO.exists(path)) {
+			throw "File doesn't exist there: "+path;
+		}
+		return readFile(path, IO.encoding);
+	},
+
+	/**
+	 * @param inFile 
+	 * @param outDir
+	 * @param [fileName=The original filename]
+	 */
+	copyFile: function(/**string*/ inFile, /**string*/ outDir, /**string*/ fileName) {
+		if (fileName == null) fileName = FilePath.fileName(inFile);
+	
+		var inFile = new File(inFile);
+		var outFile = new File(outDir+SYS.slash+fileName);
+		
+		var bis = new Packages.java.io.BufferedInputStream(new Packages.java.io.FileInputStream(inFile), 4096);
+		var bos = new Packages.java.io.BufferedOutputStream(new Packages.java.io.FileOutputStream(outFile), 4096);
+		var theChar;
+		while ((theChar = bis.read()) != -1) {
+			bos.write(theChar);
+		}
+		bos.close();
+		bis.close();
+	},
+
+	/**
+	 * Creates a series of nested directories.
+	 */
+	mkPath: function(/**Array*/ path) {
+		if (path.constructor != Array) path = path.split(/[\\\/]/);
+		var make = "";
+		for (var i = 0, l = path.length; i < l; i++) {
+			make += path[i] + SYS.slash;
+			if (! IO.exists(make)) {
+				IO.makeDir(make);
+			}
+		}
+	},
+	
+	/**
+	 * Creates a directory at the given path.
+	 */
+	makeDir: function(/**string*/ path) {
+		(new File(path)).mkdir();
+	},
+
+	/**
+	 * @type string[]
+	 * @param dir The starting directory to look in.
+	 * @param [recurse=1] How many levels deep to scan.
+	 * @returns An array of all the paths to files in the given dir.
+	 */
+	ls: function(/**string*/ dir, /**number*/ recurse, _allFiles, _path) {
+		if (_path === undefined) { // initially
+			var _allFiles = [];
+			var _path = [dir];
+		}
+		if (_path.length == 0) return _allFiles;
+		if (recurse === undefined) recurse = 1;
+		
+		dir = new File(dir);
+		if (!dir.directory) return [String(dir)];
+		var files = dir.list();
+		
+		for (var f = 0; f < files.length; f++) {
+			var file = String(files[f]);
+			if (file.match(/^\.[^\.\/\\]/)) continue; // skip dot files
+	
+			if ((new File(_path.join(SYS.slash)+SYS.slash+file)).list()) { // it's a directory
+				_path.push(file);
+				if (_path.length-1 < recurse) IO.ls(_path.join(SYS.slash), recurse, _allFiles, _path);
+				_path.pop();
+			}
+			else {
+				_allFiles.push((_path.join(SYS.slash)+SYS.slash+file).replace(SYS.slash+SYS.slash, SYS.slash));
+			}
+		}
+	
+		return _allFiles;
+	},
+
+	/**
+	 * @type boolean
+	 */
+	exists: function(/**string*/ path) {
+		file = new File(path);
+	
+		if (file.isDirectory()){
+			return true;
+		}
+		if (!file.exists()){
+			return false;
+		}
+		if (!file.canRead()){
+			return false;
+		}
+		return true;
+	},
+
+	/**
+	 * 
+	 */
+	open: function(/**string*/ path, /**string*/ append) {
+		var append = true;
+		var outFile = new File(path);
+		var out = new Packages.java.io.PrintWriter(
+			new Packages.java.io.OutputStreamWriter(
+				new Packages.java.io.FileOutputStream(outFile, append),
+				IO.encoding
+			)
+		);
+		return out;
+	},
+
+	/**
+	 * Sets {@link IO.encoding}.
+	 * Encoding is used when reading and writing text to files,
+	 * and in the meta tags of HTML output.
+	 */
+	setEncoding: function(/**string*/ encoding) {
+		if (/ISO-8859-([0-9]+)/i.test(encoding)) {
+			IO.encoding = "ISO8859_"+RegExp.$1;
+		}
+		else {
+			IO.encoding = encoding;
+		}
+	},
+
+	/**
+	 * @default "utf-8"
+	 * @private
+	 */
+	encoding: "utf-8",
+	
+	/**
+	 * Load the given script.
+	 */
+	include: function(relativePath) {
+		load(SYS.pwd+relativePath);
+	},
+	
+	/**
+	 * Loads all scripts from the given directory path.
+	 */
+	includeDir: function(path) {
+		if (!path) return;
+		
+		for (var lib = IO.ls(SYS.pwd+path), i = 0; i < lib.length; i++) 
+			if (/\.js$/i.test(lib[i])) load(lib[i]);
+	}
+}
+
+// now run the application
+IO.include("frame.js");
+IO.include("main.js");
+
+main();