/tags/jsdoc_toolkit-2.0.1/jsdoc-toolkit/app/lib/JSDOC/Parser.js

  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		// if a symbol alias is documented more than once the last one with the user docs wins
 19		if (JSDOC.Parser.symbols.hasSymbol(symbol.alias)) {
 20			var oldSymbol = JSDOC.Parser.symbols.getSymbol(symbol.alias);
 21
 22			if (oldSymbol.comment.isUserComment) {
 23				if (symbol.comment.isUserComment) { // old and new are both documented
 24					LOG.warn("The symbol '"+symbol.alias+"' is documented more than once.");
 25				}
 26				else { // old is documented but new isn't
 27					return;
 28				}
 29			}
 30		}
 31		
 32		// we don't document anonymous things
 33		if (JSDOC.Parser.conf.ignoreAnonymous && symbol.name.match(/\$anonymous\b/)) return;
 34
 35		// uderscored things may be treated as if they were marked private, this cascades
 36		if (JSDOC.Parser.conf.treatUnderscoredAsPrivate && symbol.name.match(/[.#-]_[^.#-]+$/)) {
 37			symbol.isPrivate = true;
 38		}
 39		
 40		// -p flag is required to document private things
 41		if ((symbol.isInner || symbol.isPrivate) && !JSDOC.opt.p) return;
 42		
 43		// ignored things are not documented, this doesn't cascade
 44		if (symbol.isIgnored) return;
 45		
 46		JSDOC.Parser.symbols.addSymbol(symbol);
 47	},
 48	
 49	addBuiltin: function(name) {
 50		var builtin = new JSDOC.Symbol(name, [], "CONSTRUCTOR", new JSDOC.DocComment(""));
 51		builtin.isNamespace = true;
 52		builtin.srcFile = "";
 53		builtin.isPrivate = false;
 54		JSDOC.Parser.addSymbol(builtin);
 55		return builtin;
 56	},
 57	
 58	init: function() {
 59		JSDOC.Parser.symbols = new JSDOC.SymbolSet();
 60		JSDOC.Parser.walker = new JSDOC.Walker();
 61	},
 62	
 63	finish: function() {
 64		JSDOC.Parser.symbols.relate();		
 65		
 66		// make a litle report about what was found
 67		if (JSDOC.Parser.conf.explain) {
 68			var symbols = JSDOC.Parser.symbols.toArray();
 69			var srcFile = "";
 70			for (var i = 0, l = symbols.length; i < l; i++) {
 71				var symbol = symbols[i];
 72				if (srcFile != symbol.srcFile) {
 73					srcFile = symbol.srcFile;
 74					print("\n"+srcFile+"\n-------------------");
 75				}
 76				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);
 77			}
 78			print("-------------------\n");
 79		}
 80	}
 81}
 82
 83JSDOC.Parser.parse = function(/**JSDOC.TokenStream*/ts, /**String*/srcFile) {
 84	JSDOC.Symbol.srcFile = (srcFile || "");
 85	JSDOC.DocComment.shared = ""; // shared comments don't cross file boundaries
 86	
 87	if (!JSDOC.Parser.walker) JSDOC.Parser.init();
 88	JSDOC.Parser.walker.walk(ts); // adds to our symbols
 89	
 90	// filter symbols by option
 91	for (p in JSDOC.Parser.symbols._index) {
 92		var symbol = JSDOC.Parser.symbols.getSymbol(p);
 93		
 94		if (!symbol) continue;
 95		
 96		if (symbol.is("FILE") || symbol.is("GLOBAL")) {
 97			continue;
 98		}
 99		else if (!JSDOC.opt.a && !symbol.comment.isUserComment) {
100			JSDOC.Parser.symbols.deleteSymbol(symbol.alias);
101		}
102		
103		if (/#$/.test(symbol.alias)) { // we don't document prototypes
104			JSDOC.Parser.symbols.deleteSymbol(symbol.alias);
105		}
106	}
107	
108	return JSDOC.Parser.symbols.toArray();
109}