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

  1if (typeof JSDOC == "undefined") JSDOC = {};
  2
  3/** @constructor */
  4JSDOC.SymbolSet = function() {
  5	this.init();
  6}
  7
  8JSDOC.SymbolSet.prototype.init = function() {
  9	this._index = {};
 10}
 11
 12JSDOC.SymbolSet.prototype.keys = function() {
 13	var found = [];
 14	for (var p in this._index) {
 15		found.push(p);
 16	}
 17	return found;
 18}
 19
 20JSDOC.SymbolSet.prototype.hasSymbol = function(alias) {
 21	return this._index.hasOwnProperty(alias);
 22}
 23
 24JSDOC.SymbolSet.prototype.addSymbol = function(symbol) {
 25	if (this.hasSymbol(symbol.alias)) {
 26		LOG.warn("Overwriting symbol documentation for: "+symbol.alias + ".");
 27	}
 28	this._index[symbol.alias] = symbol;
 29}
 30
 31JSDOC.SymbolSet.prototype.getSymbol = function(alias) {
 32	if (this.hasSymbol(alias)) return this._index[alias];
 33}
 34
 35JSDOC.SymbolSet.prototype.getSymbolByName = function(name) {
 36	for (var p in this._index) {
 37		var symbol = this.getSymbol(p);
 38		if (symbol.name == name) return symbol;
 39	}
 40}
 41
 42JSDOC.SymbolSet.prototype.toArray = function() {
 43	var found = [];
 44	for (var p in this._index) {
 45		found.push(this._index[p]);
 46	}
 47	return found;
 48}
 49
 50JSDOC.SymbolSet.prototype.deleteSymbol = function(alias) {
 51	if (!this.hasSymbol(alias)) return;
 52	delete this._index[alias];
 53}
 54
 55JSDOC.SymbolSet.prototype.renameSymbol = function(oldName, newName) {
 56	// todo: should check if oldname or newname already exist
 57	this._index[newName] = this._index[oldName];
 58	this.deleteSymbol(oldName);
 59	this._index[newName].alias = newName;
 60	return newName;
 61}
 62
 63JSDOC.SymbolSet.prototype.relate = function() {
 64	this.resolveBorrows();
 65	this.resolveMemberOf();
 66	this.resolveAugments();
 67}
 68
 69JSDOC.SymbolSet.prototype.resolveBorrows = function() {
 70	for (p in this._index) {
 71		var symbol = this._index[p];
 72		if (symbol.is("FILE") || symbol.is("GLOBAL")) continue;
 73		
 74		var borrows = symbol.inherits;
 75		for (var i = 0; i < borrows.length; i++) {
 76			var borrowed = this.getSymbol(borrows[i].alias);
 77			if (!borrowed) {
 78				LOG.warn("Can't borrow undocumented "+borrows[i].alias+".");
 79				continue;
 80			}
 81			
 82			var borrowAsName = borrows[i].as;
 83			var borrowAsAlias = borrowAsName;
 84			if (!borrowAsName) {
 85				LOG.warn("Malformed @borrow, 'as' is required.");
 86				continue;
 87			}
 88			
 89			if (borrowAsName.length > symbol.alias.length && borrowAsName.indexOf(symbol.alias) == 0) {
 90				borrowAsName = borrowAsName.replace(borrowed.alias, "")
 91			}
 92			else {
 93				var joiner = "";
 94				if (borrowAsName.charAt(0) != "#") joiner = ".";
 95				borrowAsAlias = borrowed.alias + joiner + borrowAsName;
 96			}
 97			
 98			borrowAsName = borrowAsName.replace(/^[#.]/, "");
 99					
100			if (this.hasSymbol(borrowAsAlias)) continue;
101
102			var clone = borrowed.clone();
103			clone.name = borrowAsName;
104			clone.alias = borrowAsAlias;
105			this.addSymbol(clone);
106		}
107	}
108}
109
110JSDOC.SymbolSet.prototype.resolveMemberOf = function() {
111	for (var p in this._index) {
112		var symbol = this.getSymbol(p);
113		
114		if (symbol.is("FILE") || symbol.is("GLOBAL")) continue;
115		
116		// the memberOf value was provided in the @memberOf tag
117		else if (symbol.memberOf) {
118			var parts = symbol.alias.match(new RegExp("^("+symbol.memberOf+"[.#-])(.+)$"));
119			
120			// like foo.bar is a memberOf foo
121			if (parts) {
122				symbol.memberOf = parts[1];
123				symbol.name = parts[2];
124			}
125			// like bar is a memberOf foo
126			else {
127				var joiner = symbol.memberOf.charAt(symbol.memberOf.length-1);
128				if (!/[.#-]/.test(joiner)) symbol.memberOf += ".";
129				
130				this.renameSymbol(p, symbol.memberOf + symbol.name);
131			}
132		}
133		// the memberOf must be calculated
134		else {
135			var parts = symbol.alias.match(/^(.*[.#-])([^.#-]+)$/);
136			if (parts) {
137				symbol.memberOf = parts[1];
138				symbol.name = parts[2];				
139			}
140		}
141
142		// set isStatic, isInner
143		if (symbol.memberOf) {
144			switch (symbol.memberOf.charAt(symbol.memberOf.length-1)) {
145				case '#' :
146					symbol.isStatic = false;
147					symbol.isInner = false;
148				break;
149				case '.' :
150					symbol.isStatic = true;
151					symbol.isInner = false;
152				break;
153				case '-' :
154					symbol.isStatic = false;
155					symbol.isInner = true;
156				break;
157			}
158		}
159		
160		// unowned methods and fields belong to the global object
161		if (!symbol.is("CONSTRUCTOR") && !symbol.isNamespace && symbol.memberOf == "") {
162			symbol.memberOf = "_global_";
163		}
164		
165		// clean up
166		if (symbol.memberOf.match(/[.#-]$/)) {
167			symbol.memberOf = symbol.memberOf.substr(0, symbol.memberOf.length-1);
168		}
169		
170		// add to parent's methods or properties list
171		if (symbol.memberOf) {
172			var container = this.getSymbol(symbol.memberOf);
173			if (!container) {
174				if (JSDOC.Lang.isBuiltin(symbol.memberOf)) container = JSDOC.Parser.addBuiltin(symbol.memberOf);
175				else {
176					LOG.warn("Can't document "+symbol.name +" as a member of undocumented symbol "+symbol.memberOf+".");
177				}
178			}
179			
180			if (container) container.addMember(symbol);
181		}
182	}
183}
184
185JSDOC.SymbolSet.prototype.resolveAugments = function() {
186	for (var p in this._index) {
187		var symbol = this.getSymbol(p);
188		
189		if (symbol.alias == "_global_" || symbol.is("FILE")) continue;
190		JSDOC.SymbolSet.prototype.walk.apply(this, [symbol]);
191	}
192}
193
194JSDOC.SymbolSet.prototype.walk = function(symbol) {
195	var augments = symbol.augments;
196	for(var i = 0; i < augments.length; i++) {
197		var contributer = this.getSymbol(augments[i]);
198		if (contributer) {
199			if (contributer.augments.length) {
200				JSDOC.SymbolSet.prototype.walk.apply(this, [contributer]);
201			}
202			
203			symbol.inheritsFrom.push(contributer.alias);
204			if (!isUnique(symbol.inheritsFrom)) {
205				//LOG.warn("Can't resolve augments: Circular reference: "+symbol.alias+" inherits from "+contributer.alias+" more than once.");
206			}
207			else {
208				var cmethods = contributer.methods;
209				var cproperties = contributer.properties;
210				
211				for (var ci = 0, cl = cmethods.length; ci < cl; ci++)
212					symbol.inherit(cmethods[ci]);
213				for (var ci = 0, cl = cproperties.length; ci < cl; ci++)
214					symbol.inherit(cproperties[ci]);
215			}
216		}
217		else LOG.warn("Can't augment contributer: "+augments[i]+", not found.");
218	}
219}
220