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