1 if (typeof JSDOC == "undefined") JSDOC = {}; |
|
2 |
|
3 /** |
|
4 @namespace |
|
5 @requires JSDOC.Walker |
|
6 @requires JSDOC.Symbol |
|
7 @requires JSDOC.DocComment |
|
8 */ |
|
9 JSDOC.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 |
|
120 JSDOC.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 } |
|