Commit | Line | Data |
---|---|---|
629a09ae DV |
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 | } |