ragaskar-jsdoc_helper 0.0.2.1

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

@@ -0,0 +1,126 @@
+/**
+	@constructor
+	@param [opt] Used to override the commandline options. Useful for testing.
+	@version $Id: JsDoc.js 769 2009-01-11 12:13:00Z micmath $
+*/
+JSDOC.JsDoc = function(/**object*/ opt) {
+	if (opt) {
+		JSDOC.opt = opt;
+	}
+	
+	if (JSDOC.opt.h) {
+		JSDOC.usage();
+		quit();
+	}
+	
+	// defend against options that are not sane 
+	if (JSDOC.opt._.length == 0) {
+		LOG.warn("No source files to work on. Nothing to do.");
+		quit();
+	}
+	if (JSDOC.opt.t === true || JSDOC.opt.d === true) {
+		JSDOC.usage();
+	}
+	
+	if (typeof JSDOC.opt.d == "string") {
+		if (!JSDOC.opt.d.charAt(JSDOC.opt.d.length-1).match(/[\\\/]/)) {
+			JSDOC.opt.d = JSDOC.opt.d+"/";
+		}
+		LOG.inform("Output directory set to '"+JSDOC.opt.d+"'.");
+		IO.mkPath(JSDOC.opt.d);
+	}
+	if (JSDOC.opt.e) IO.setEncoding(JSDOC.opt.e);
+	
+	// the -r option: scan source directories recursively
+	if (typeof JSDOC.opt.r == "boolean") JSDOC.opt.r = 10;
+	else if (!isNaN(parseInt(JSDOC.opt.r))) JSDOC.opt.r = parseInt(JSDOC.opt.r);
+	else JSDOC.opt.r = 1;
+	
+	// the -D option: define user variables
+	var D = {};
+	if (JSDOC.opt.D) {
+		for (var i = 0; i < JSDOC.opt.D.length; i++) {
+			var defineParts = JSDOC.opt.D[i].split(":", 2);
+			if (defineParts) D[defineParts[0]] = defineParts[1];
+		}
+	}
+	JSDOC.opt.D = D;
+	// combine any conf file D options with the commandline D options
+	if (defined(JSDOC.conf)) for (var c in JSDOC.conf.D) {
+ 		if (!defined(JSDOC.opt.D[c])) {
+ 			JSDOC.opt.D[c] = JSDOC.conf.D[c];
+ 		}
+ 	}
+	
+	// Give plugins a chance to initialize
+	if (defined(JSDOC.PluginManager)) {
+		JSDOC.PluginManager.run("onInit", JSDOC.opt);
+	}
+
+	JSDOC.opt.srcFiles = JSDOC.JsDoc._getSrcFiles();
+	JSDOC.JsDoc._parseSrcFiles();
+	JSDOC.JsDoc.symbolSet = JSDOC.Parser.symbols;
+}
+
+/**
+	Retrieve source file list.
+	@returns {String[]} The pathnames of the files to be parsed.
+ */
+JSDOC.JsDoc._getSrcFiles = function() {
+	JSDOC.JsDoc.srcFiles = [];
+	
+	var ext = ["js"];
+	if (JSDOC.opt.x) {
+		ext = JSDOC.opt.x.split(",").map(function($) {return $.toLowerCase()});
+	}
+	
+	for (var i = 0; i < JSDOC.opt._.length; i++) {
+		JSDOC.JsDoc.srcFiles = JSDOC.JsDoc.srcFiles.concat(
+			IO.ls(JSDOC.opt._[i], JSDOC.opt.r).filter(
+				function($) {
+					var thisExt = $.split(".").pop().toLowerCase();
+					
+					if (JSDOC.opt.E) {
+						for(var n = 0; n < JSDOC.opt.E.length; n++) {
+							if ($.match(new RegExp(JSDOC.opt.E[n]))) {
+								LOG.inform("Excluding " + $);
+								return false; // if the file matches the regex then it's excluded.
+							}
+						}
+					}
+					
+					return (ext.indexOf(thisExt) > -1 || thisExt in JSDOC.handlers); // we're only interested in files with certain extensions
+				}
+			)
+		);
+	}
+	
+	return JSDOC.JsDoc.srcFiles;
+}
+
+JSDOC.JsDoc._parseSrcFiles = function() {
+	JSDOC.Parser.init();
+	for (var i = 0, l = JSDOC.JsDoc.srcFiles.length; i < l; i++) {
+		var srcFile = JSDOC.JsDoc.srcFiles[i];
+		
+		if (JSDOC.opt.v) LOG.inform("Parsing file: " + srcFile);
+		
+		try {
+			var src = IO.readFile(srcFile);
+		}
+		catch(e) {
+			LOG.warn("Can't read source file '"+srcFile+"': "+e.message);
+		}
+
+		var tr = new JSDOC.TokenReader();
+		var ts = new JSDOC.TokenStream(tr.tokenize(new JSDOC.TextStream(src)));
+
+		JSDOC.Parser.parse(ts, srcFile);
+
+	}
+	JSDOC.Parser.finish();
+
+	if (JSDOC.PluginManager) {
+		JSDOC.PluginManager.run("onFinishedParsing", JSDOC.Parser.symbols);
+	}
+}

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

@@ -0,0 +1,109 @@
+/**
+	@constructor
+*/
+JSDOC.JsPlate = function(templateFile) {
+	if (templateFile) this.template = IO.readFile(templateFile);
+	
+	this.templateFile = templateFile;
+	this.code = "";
+	this.parse();
+}
+
+JSDOC.JsPlate.prototype.parse = function() {
+	this.template = this.template.replace(/\{#[\s\S]+?#\}/gi, "");
+	this.code = "var output=``"+this.template;
+
+	this.code = this.code.replace(
+		/<for +each="(.+?)" +in="(.+?)" *>/gi, 
+		function (match, eachName, inName) {
+			return "``;\rvar $"+eachName+"_keys = keys("+inName+");\rfor(var $"+eachName+"_i = 0; $"+eachName+"_i < $"+eachName+"_keys.length; $"+eachName+"_i++) {\rvar $"+eachName+"_last = ($"+eachName+"_i == $"+eachName+"_keys.length-1);\rvar $"+eachName+"_key = $"+eachName+"_keys[$"+eachName+"_i];\rvar "+eachName+" = "+inName+"[$"+eachName+"_key];\routput+=``";
+		}
+	);	
+	this.code = this.code.replace(/<if test="(.+?)">/g, "``;\rif ($1) { output+=``");
+	this.code = this.code.replace(/<elseif test="(.+?)"\s*\/>/g, "``;}\relse if ($1) { output+=``");
+	this.code = this.code.replace(/<else\s*\/>/g, "``;}\relse { output+=``");
+	this.code = this.code.replace(/<\/(if|for)>/g, "``;\r};\routput+=``");
+	this.code = this.code.replace(
+		/\{\+\s*([\s\S]+?)\s*\+\}/gi,
+		function (match, code) {
+			code = code.replace(/"/g, "``"); // prevent qoute-escaping of inline code
+			code = code.replace(/(\r?\n)/g, " ");
+			return "``+ ("+code+") +``";
+		}
+	);
+	this.code = this.code.replace(
+		/\{!\s*([\s\S]+?)\s*!\}/gi,
+		function (match, code) {
+			code = code.replace(/"/g, "``"); // prevent qoute-escaping of inline code
+			code = code.replace(/(\n)/g, " ");
+			return "``; "+code+";\routput+=``";
+		}
+	);
+	this.code = this.code+"``;";
+
+	this.code = this.code.replace(/(\r?\n)/g, "\\n");
+	this.code = this.code.replace(/"/g, "\\\"");
+	this.code = this.code.replace(/``/g, "\"");
+}
+
+JSDOC.JsPlate.prototype.toCode = function() {
+	return this.code;
+}
+
+JSDOC.JsPlate.keys = function(obj) {
+	var keys = [];
+	if (obj.constructor.toString().indexOf("Array") > -1) {
+		for (var i = 0; i < obj.length; i++) {
+			keys.push(i);
+		}
+	}
+	else {
+		for (var i in obj) {
+			keys.push(i);
+		}
+	}
+	return keys;
+};
+
+JSDOC.JsPlate.values = function(obj) {
+	var values = [];
+	if (obj.constructor.toString().indexOf("Array") > -1) {
+		for (var i = 0; i < obj.length; i++) {
+			values.push(obj[i]);
+		}
+	}
+	else {
+		for (var i in obj) {
+			values.push(obj[i]);
+		}
+	}
+	return values;
+};
+
+JSDOC.JsPlate.prototype.process = function(data, compact) {
+	var keys = JSDOC.JsPlate.keys;
+	var values = JSDOC.JsPlate.values;
+	
+	try {
+		eval(this.code);
+	}
+	catch (e) {
+		print(">> There was an error evaluating the compiled code from template: "+this.templateFile);
+		print("   The error was on line "+e.lineNumber+" "+e.name+": "+e.message);
+		var lines = this.code.split("\r");
+		if (e.lineNumber-2 >= 0) print("line "+(e.lineNumber-1)+": "+lines[e.lineNumber-2]);
+		print("line "+e.lineNumber+": "+lines[e.lineNumber-1]);
+		print("");
+	}
+	
+	if (compact) { // patch by mcbain.asm
+ 		// Remove lines that contain only space-characters, usually left by lines in the template
+ 		// which originally only contained JSPlate tags or code. This makes it easier to write
+ 		// non-tricky templates which still put out nice code (not bloated with extra lines).
+ 		// Lines purposely left blank (just a line ending) are left alone.
+ 		output = output.replace(/\s+?(\r?)\n/g, "$1\n");
+ 	}
+ 	
+	/*debug*///print(this.code);
+	return output;
+}

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

@@ -0,0 +1,144 @@
+/**
+	@namespace
+*/
+JSDOC.Lang = {
+}
+
+JSDOC.Lang.isBuiltin = function(name) {
+	return (JSDOC.Lang.isBuiltin.coreObjects.indexOf(name) > -1);
+}
+JSDOC.Lang.isBuiltin.coreObjects = ['_global_', 'Array', 'Boolean', 'Date', 'Error', 'Function', 'Math', 'Number', 'Object', 'RegExp', 'String'];
+
+JSDOC.Lang.whitespace = function(ch) {
+	return JSDOC.Lang.whitespace.names[ch];
+}
+JSDOC.Lang.whitespace.names = {
+	" ":      "SPACE",
+	"\f":     "FORMFEED",
+	"\t":     "TAB",
+	"\u0009": "UNICODE_TAB",
+	"\u000A": "UNICODE_NBR",
+	"\u0008": "VERTICAL_TAB"
+};
+
+JSDOC.Lang.newline = function(ch) {
+	return JSDOC.Lang.newline.names[ch];
+}
+JSDOC.Lang.newline.names = {
+	"\n":     "NEWLINE",
+	"\r":     "RETURN",
+	"\u000A": "UNICODE_LF",
+	"\u000D": "UNICODE_CR",
+	"\u2029": "UNICODE_PS",
+	"\u2028": "UNICODE_LS"
+};
+
+JSDOC.Lang.keyword = function(word) {
+	return JSDOC.Lang.keyword.names["="+word];
+}
+JSDOC.Lang.keyword.names = {
+	"=break":      "BREAK",
+	"=case":       "CASE",
+	"=catch":      "CATCH",
+	"=const":      "VAR",
+	"=continue":   "CONTINUE",
+	"=default":    "DEFAULT",
+	"=delete":     "DELETE",
+	"=do":         "DO",
+	"=else":       "ELSE",
+	"=false":      "FALSE",
+	"=finally":    "FINALLY",
+	"=for":        "FOR",
+	"=function":   "FUNCTION",
+	"=if":         "IF",
+	"=in":         "IN",
+	"=instanceof": "INSTANCEOF",
+	"=new":        "NEW",
+	"=null":       "NULL",
+	"=return":     "RETURN",
+	"=switch":     "SWITCH",
+	"=this":       "THIS",
+	"=throw":      "THROW",
+	"=true":       "TRUE",
+	"=try":        "TRY",
+	"=typeof":     "TYPEOF",
+	"=void":       "VOID",
+	"=while":      "WHILE",
+	"=with":       "WITH",
+	"=var":        "VAR"
+};
+
+JSDOC.Lang.punc = function(ch) {
+	return JSDOC.Lang.punc.names[ch];
+}
+JSDOC.Lang.punc.names = {
+	";":   "SEMICOLON",
+	",":   "COMMA",
+	"?":   "HOOK",
+	":":   "COLON",
+	"||":  "OR", 
+	"&&":  "AND",
+	"|":   "BITWISE_OR",
+	"^":   "BITWISE_XOR",
+	"&":   "BITWISE_AND",
+	"===": "STRICT_EQ", 
+	"==":  "EQ",
+	"=":   "ASSIGN",
+	"!==": "STRICT_NE",
+	"!=":  "NE",
+	"<<":  "LSH",
+	"<=":  "LE", 
+	"<":   "LT",
+	">>>": "URSH",
+	">>":  "RSH",
+	">=":  "GE",
+	">":   "GT", 
+	"++":  "INCREMENT",
+	"--":  "DECREMENT",
+	"+":   "PLUS",
+	"-":   "MINUS",
+	"*":   "MUL",
+	"/":   "DIV", 
+	"%":   "MOD",
+	"!":   "NOT",
+	"~":   "BITWISE_NOT",
+	".":   "DOT",
+	"[":   "LEFT_BRACKET",
+	"]":   "RIGHT_BRACKET",
+	"{":   "LEFT_CURLY",
+	"}":   "RIGHT_CURLY",
+	"(":   "LEFT_PAREN",
+	")":   "RIGHT_PAREN"
+};
+
+JSDOC.Lang.matching = function(name) {
+	return JSDOC.Lang.matching.names[name];
+}
+JSDOC.Lang.matching.names = {
+	"LEFT_PAREN": "RIGHT_PAREN",
+	"RIGHT_PAREN": "LEFT_PAREN",
+	"LEFT_CURLY": "RIGHT_CURLY",
+	"RIGHT_CURLY": "LEFT_CURLY",
+	"LEFT_BRACE": "RIGHT_BRACE",
+	"RIGHT_BRACE": "LEFT_BRACE"
+}
+
+JSDOC.Lang.isNumber = function(str) {
+	return /^(\.[0-9]|[0-9]+\.|[0-9])[0-9]*([eE][+-][0-9]+)?$/i.test(str);
+}
+
+JSDOC.Lang.isHexDec = function(str) {
+	return /^0x[0-9A-F]+$/i.test(str);
+}
+
+JSDOC.Lang.isWordChar = function(str) {
+	return /^[a-zA-Z0-9$_.]+$/.test(str);
+}
+
+JSDOC.Lang.isSpace = function(str) {
+	return (typeof JSDOC.Lang.whitespace(str) != "undefined");
+}
+
+JSDOC.Lang.isNewline = function(str) {
+	return (typeof JSDOC.Lang.newline(str) != "undefined");
+}

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

@@ -0,0 +1,107 @@
+if (typeof JSDOC == "undefined") JSDOC = {};
+
+/**
+	@namespace
+	@requires JSDOC.Walker
+	@requires JSDOC.Symbol
+	@requires JSDOC.DocComment
+*/
+JSDOC.Parser = {
+	conf: {
+		ignoreCode:               JSDOC.opt.n,
+		ignoreAnonymous:           true, // factory: true
+		treatUnderscoredAsPrivate: true, // factory: true
+		explain:                   false // factory: false
+	},
+	
+	addSymbol: function(symbol) {
+		// if a symbol alias is documented more than once the last one with the user docs wins
+		if (JSDOC.Parser.symbols.hasSymbol(symbol.alias)) {
+ 			var oldSymbol = JSDOC.Parser.symbols.getSymbol(symbol.alias);
+			if (oldSymbol.comment.isUserComment) {
+				if (symbol.comment.isUserComment) { // old and new are both documented
+					LOG.warn("The symbol '"+symbol.alias+"' is documented more than once.");
+				}
+				else { // old is documented but new isn't
+					return;
+				}
+			}
+		}
+		
+		// we don't document anonymous things
+		if (JSDOC.Parser.conf.ignoreAnonymous && symbol.name.match(/\$anonymous\b/)) return;
+
+		// uderscored things may be treated as if they were marked private, this cascades
+		if (JSDOC.Parser.conf.treatUnderscoredAsPrivate && symbol.name.match(/[.#-]_[^.#-]+$/)) {
+			if (!symbol.comment.getTag("public").length > 0) symbol.isPrivate = true;
+		}
+		
+		// -p flag is required to document private things
+		if (!JSDOC.opt.p && symbol.isPrivate) return; // issue #161 fixed by mcbain.asm
+		
+		// ignored things are not documented, this doesn't cascade
+		if (symbol.isIgnored) return;
+		JSDOC.Parser.symbols.addSymbol(symbol);
+	},
+	
+	addBuiltin: function(name) {
+		var builtin = new JSDOC.Symbol(name, [], "CONSTRUCTOR", new JSDOC.DocComment(""));
+		builtin.isNamespace = true;
+		builtin.srcFile = "";
+		builtin.isPrivate = false;
+		JSDOC.Parser.addSymbol(builtin);
+		return builtin;
+	},
+	
+	init: function() {
+		JSDOC.Parser.symbols = new JSDOC.SymbolSet();
+		JSDOC.Parser.walker = new JSDOC.Walker();
+	},
+	
+	finish: function() {
+		JSDOC.Parser.symbols.relate();		
+		
+		// make a litle report about what was found
+		if (JSDOC.Parser.conf.explain) {
+			var symbols = JSDOC.Parser.symbols.toArray();
+			var srcFile = "";
+			for (var i = 0, l = symbols.length; i < l; i++) {
+				var symbol = symbols[i];
+				if (srcFile != symbol.srcFile) {
+					srcFile = symbol.srcFile;
+					print("\n"+srcFile+"\n-------------------");
+				}
+				print(i+":\n  alias => "+symbol.alias + "\n  name => "+symbol.name+ "\n  isa => "+symbol.isa + "\n  memberOf => " + symbol.memberOf + "\n  isStatic => " + symbol.isStatic + ",  isInner => " + symbol.isInner+ ",  isPrivate => " + symbol.isPrivate);
+			}
+			print("-------------------\n");
+		}
+	}
+}
+
+JSDOC.Parser.parse = function(/**JSDOC.TokenStream*/ts, /**String*/srcFile) {
+	JSDOC.Symbol.srcFile = (srcFile || "");
+	JSDOC.DocComment.shared = ""; // shared comments don't cross file boundaries
+	
+	if (!JSDOC.Parser.walker) JSDOC.Parser.init();
+	JSDOC.Parser.walker.walk(ts); // adds to our symbols
+	
+	// filter symbols by option
+	for (var p = JSDOC.Parser.symbols._index.first(); p; p = JSDOC.Parser.symbols._index.next()) {
+		var symbol = p.value;
+		
+		if (!symbol) continue;
+		
+		if (symbol.is("FILE") || symbol.is("GLOBAL")) {
+			continue;
+		}
+		else if (!JSDOC.opt.a && !symbol.comment.isUserComment) {
+			JSDOC.Parser.symbols.deleteSymbol(symbol.alias);
+		}
+		
+		if (/#$/.test(symbol.alias)) { // we don't document prototypes
+			JSDOC.Parser.symbols.deleteSymbol(symbol.alias);
+		}
+	}
+	
+	return JSDOC.Parser.symbols.toArray();
+}