PageRenderTime 27ms CodeModel.GetById 10ms app.highlight 14ms RepoModel.GetById 1ms app.codeStats 0ms

/trunk/jsdoc-toolkit/app/lib/JSDOC/Parser.js

http://jsdoc-toolkit.googlecode.com/
JavaScript | 146 lines | 110 code | 22 blank | 14 comment | 41 complexity | cc3b4cb88757a149a72eb76bbe7cd7a5 MD5 | raw file
  1if (typeof JSDOC == "undefined") JSDOC = {};
  2
  3/**
  4	@namespace
  5	@requires JSDOC.Walker
  6	@requires JSDOC.Symbol
  7	@requires JSDOC.DocComment
  8*/
  9JSDOC.Parser = {
 10	conf: {
 11		ignoreCode:               JSDOC.opt.n,
 12		ignoreAnonymous:           true, // factory: true
 13		treatUnderscoredAsPrivate: true, // factory: true
 14		explain:                   false // factory: false
 15	},
 16	
 17	addSymbol: function(symbol) {
 18
 19		if (JSDOC.Parser.rename) {
 20			for (var n in JSDOC.Parser.rename) {
 21				if (symbol.alias.indexOf(n) == 0) {
 22					if (symbol.name == symbol.alias) {
 23						symbol.name = symbol.name.replace(n, JSDOC.Parser.rename[n]);
 24					}
 25					symbol.alias = symbol.alias.replace(n, JSDOC.Parser.rename[n]);
 26				}
 27			}
 28		}
 29		
 30		if (JSDOC.opt.S) {
 31			if (typeof JSDOC.Parser.secureModules == "undefined") JSDOC.Parser.secureModules = {};
 32			if (/^exports\./.test(symbol.alias)) {
 33				symbol.srcFile.match(/(^|[\\\/])([^\\\/]+)\.js/i);
 34				var fileNS = RegExp.$2;
 35				
 36				// need to create the namespace associated with this file first
 37				if (!JSDOC.Parser.secureModules[fileNS]) {
 38					JSDOC.Parser.secureModules[fileNS] = 1;
 39					var nsSymbol = new JSDOC.Symbol(fileNS, [], "GLOBAL", new JSDOC.DocComment(""));
 40					nsSymbol.isNamespace = true;
 41					nsSymbol.srcFile = "";
 42					nsSymbol.isPrivate = false;
 43					nsSymbol.srcFile = symbol.srcFile;
 44					nsSymbol.desc = (JSDOC.Parser.symbols.getSymbol(symbol.srcFile) || {desc: ""}).desc;
 45					JSDOC.Parser.addSymbol(nsSymbol);
 46				}
 47				
 48				symbol.alias = symbol.alias.replace(/^exports\./, fileNS + '.');
 49				symbol.name = symbol.name.replace(/^exports\./, '');
 50				symbol.memberOf = fileNS;
 51				symbol.isStatic = true;
 52			}
 53		}
 54
 55		// if a symbol alias is documented more than once the first one with the user docs wins
 56		if (JSDOC.Parser.symbols.hasSymbol(symbol.alias)) {
 57 			var oldSymbol = JSDOC.Parser.symbols.getSymbol(symbol.alias);
 58			if (oldSymbol.comment.isUserComment) {
 59				if (JSDOC.opt.m) return;
 60				if (symbol.comment.isUserComment) { // old and new are both documented
 61					LOG.warn("The symbol '"+symbol.alias+"' is documented more than once.");
 62					return;
 63				}
 64				else { // old is documented but new isn't
 65					return;
 66				}
 67			}
 68		}
 69		
 70		// we don't document anonymous things
 71		if (JSDOC.Parser.conf.ignoreAnonymous && symbol.name.match(/\$anonymous\b/)) return;
 72
 73		// uderscored things may be treated as if they were marked private, this cascades
 74		if (JSDOC.Parser.conf.treatUnderscoredAsPrivate && symbol.name.match(/[.#-]_[^.#-]+$/)) {
 75			if (!symbol.comment.getTag("public").length > 0) symbol.isPrivate = true;
 76		}
 77		
 78		// -p flag is required to document private things
 79		if (!JSDOC.opt.p && symbol.isPrivate) return; // issue #161 fixed by mcbain.asm
 80		
 81		// ignored things are not documented, this doesn't cascade
 82		if (symbol.isIgnored) return;
 83		JSDOC.Parser.symbols.addSymbol(symbol);
 84	},
 85	
 86	addBuiltin: function(name) {
 87		var builtin = new JSDOC.Symbol(name, [], "CONSTRUCTOR", new JSDOC.DocComment(""));
 88		builtin.isNamespace = true;
 89		builtin.srcFile = "";
 90		builtin.isPrivate = false;
 91		JSDOC.Parser.addSymbol(builtin);
 92		return builtin;
 93	},
 94	
 95	init: function() {
 96		JSDOC.Parser.symbols = new JSDOC.SymbolSet();
 97		JSDOC.Parser.walker = new JSDOC.Walker();
 98	},
 99	
100	finish: function() {
101		JSDOC.Parser.symbols.relate();		
102		
103		// make a litle report about what was found
104		if (JSDOC.Parser.conf.explain) {
105			var symbols = JSDOC.Parser.symbols.toArray();
106			var srcFile = "";
107			for (var i = 0, l = symbols.length; i < l; i++) {
108				var symbol = symbols[i];
109				if (srcFile != symbol.srcFile) {
110					srcFile = symbol.srcFile;
111					print("\n"+srcFile+"\n-------------------");
112				}
113				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);
114			}
115			print("-------------------\n");
116		}
117	}
118}
119
120JSDOC.Parser.parse = function(/**JSDOC.TokenStream*/ts, /**String*/srcFile) {
121	JSDOC.Symbol.srcFile = (srcFile || "");
122	JSDOC.DocComment.shared = ""; // shared comments don't cross file boundaries
123	
124	if (!JSDOC.Parser.walker) JSDOC.Parser.init();
125	JSDOC.Parser.walker.walk(ts); // adds to our symbols
126	
127	// filter symbols by option
128	for (var p = JSDOC.Parser.symbols._index.first(); p; p = JSDOC.Parser.symbols._index.next()) {
129		var symbol = p.value;
130		
131		if (!symbol) continue;
132		
133		if (symbol.is("FILE") || symbol.is("GLOBAL")) {
134			continue;
135		}
136		else if (!JSDOC.opt.a && !symbol.comment.isUserComment) {
137			JSDOC.Parser.symbols.deleteSymbol(symbol.alias);
138		}
139		
140		if (/#$/.test(symbol.alias)) { // we don't document prototypes
141			JSDOC.Parser.symbols.deleteSymbol(symbol.alias);
142		}
143	}
144	
145	return JSDOC.Parser.symbols.toArray();
146}