quentonc-jsdoc_helper 0.0.2

data/ext/jsdoc-toolkit/app/lib/JSDOC.js

@@ -0,0 +1,101 @@
+/**
+	@overview
+	@date $Date: 2009-01-21 22:53:36 +0000 (Wed, 21 Jan 2009) $
+	@version $Revision: 771 $ 
+	@location $HeadURL: https://jsdoc-toolkit.googlecode.com/svn/tags/jsdoc_toolkit-2.1.0/jsdoc-toolkit/app/lib/JSDOC.js $
+	@name whateverFilename.js
+ */
+
+/**
+	This is the main container for the JSDOC application.
+	@namespace
+*/
+JSDOC = {
+};
+
+/**
+	@requires Opt
+ */
+if (typeof arguments == "undefined") arguments = [];
+JSDOC.opt = Opt.get(
+	arguments, 
+	{
+		d: "directory",
+		c: "conf",
+		t: "template",
+		r: "recurse",
+		x: "ext",
+		p: "private",
+		a: "allfunctions", 
+		e: "encoding",
+		n: "nocode",
+		o: "out",
+		s: "suppress",
+		q: "quiet",
+		T: "testmode",
+		h: "help",
+		v: "verbose",
+		"D[]": "define",
+		"E[]": "exclude",
+		"H[]": "handler"
+	}
+);
+
+/** The current version string of this application. */
+JSDOC.VERSION = "2.1.0";
+
+/** Print out usage information and quit. */
+JSDOC.usage = function() {
+	print("USAGE: java -jar jsrun.jar app/run.js [OPTIONS] <SRC_DIR> <SRC_FILE> ...");
+	print("");
+	print("OPTIONS:");
+	print("  -a or --allfunctions\n          Include all functions, even undocumented ones.\n");
+	print("  -c or --conf\n          Load a configuration file.\n");
+	print("  -d=<PATH> or --directory=<PATH>\n          Output to this directory (defaults to \"out\").\n");
+	print("  -D=\"myVar:My value\" or --define=\"myVar:My value\"\n          Multiple. Define a variable, available in JsDoc as JSDOC.opt.D.myVar.\n");
+	print("  -e=<ENCODING> or --encoding=<ENCODING>\n          Use this encoding to read and write files.\n");
+	print("  -E=\"REGEX\" or --exclude=\"REGEX\"\n          Multiple. Exclude files based on the supplied regex.\n");
+	print("  -h or --help\n          Show this message and exit.\n");
+	print("  -n or --nocode\n          Ignore all code, only document comments with @name tags.\n");
+	print("  -o=<PATH> or --out=<PATH>\n          Print log messages to a file (defaults to stdout).\n");
+	print("  -p or --private\n          Include symbols tagged as private, underscored and inner symbols.\n");
+	print("  -q or --quiet\n          Do not output any messages, not even warnings.\n");
+	print("  -r=<DEPTH> or --recurse=<DEPTH>\n          Descend into src directories.\n");
+	print("  -s or --suppress\n          Suppress source code output.\n");
+	print("  -t=<PATH> or --template=<PATH>\n          Required. Use this template to format the output.\n");
+	print("  -T or --test\n          Run all unit tests and exit.\n");
+	print("  -v or --verbose\n          Provide verbose feedback about what is happening.\n");
+	print("  -x=<EXT>[,EXT]... or --ext=<EXT>[,EXT]...\n          Scan source files with the given extension/s (defaults to js).\n");
+	
+	quit();
+}
+
+/*t:
+	plan(4, "Testing JSDOC namespace.");
+	
+	is(
+		typeof JSDOC,
+		"object",
+		"JSDOC.usage is a function."
+	);
+	
+	is(
+		typeof JSDOC.VERSION,
+		"string",
+		"JSDOC.VERSION is a string."
+	);
+	
+	is(
+		typeof JSDOC.usage,
+		"function",
+		"JSDOC.usage is a function."
+	);
+	
+	is(
+		typeof JSDOC.opt,
+		"object",
+		"JSDOC.opt is a object."
+	);
+ */
+
+if (this.IO) IO.includeDir("lib/JSDOC/");

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

@@ -0,0 +1,111 @@
+/**
+ * @version $Id: main.js 769 2009-01-11 12:13:00Z micmath $
+ */
+
+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 or handlers 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/ext/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/ext/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/ext/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/ext/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/ext/jsdoc-toolkit/app/plugins/symbolLink.js

@@ -0,0 +1,9 @@
+JSDOC.PluginManager.registerPlugin(
+	"JSDOC.symbolLink",
+	{
+		onSymbolLink: function(link) {
+			// modify link.linkPath
+			// or link.linkText here
+		}
+	}
+);

data/ext/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/ext/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"
+		}
+	}
+);