git.roojs.org Git - app.jsdoc/blob - JSDOC/ScopeNamer.js

   1 XObject = imports.XObject.XObject;
   2
   3
   4 console     = imports.console.console;
   5
   6 Symbol = imports.Symbol.Symbol;
   7
   8 /**
   9  * @class ScopeNamer
  10  * @extends Collapse
  11  * @namespace JSDOC
  12  * The point of this class is to iterate through the Collapsed tree
  13  * and add the property 'scopedName' to the tokens.
  14  *
  15  *
  16  *
  17
  18   After spending some time looking at this, a few conclusions...
  19
  20   - this will have to be the base class of specific implementations.
  21   - each implementation will have to decide how to declare a new scope
  22
  23   scopes are normally changed when these things occur:
  24
  25
  26   globalScope(stmts) => statementsScope($global$, stmts)
  27
  28
  29   'object'
  30   objectScope(sname, props  )
  31   a = { .... } << scope is a  $this$={a}
  32
  33      // property scopes???
  34     foo: function() {} $this$={object scope}
  35     foo : ( xxx ? function()  { } ? function() { ...} << conditional properties types
  36     foo : (function() { return x })() << a property or function??? << depends on notes
  37     foo : [ ] << a property.. do not drill down?
  38     foo : xxxxx << a property..
  39
  40
  41   'function'
  42   functionScope(sname,  stmts  )
  43   function a() { .... } << scope is a  $this$={a}
  44   a = function() { } << scope might be a  $this$={a}
  45
  46   // registers 'this.*'
  47
  48
  49
  50   'call' scopes
  51   XX.yy(a,b, { .... }) << scope might be a or b..  $this$={a}
  52   aa = XX.yy(a,b, { .... }) << scope might aa   $this$={a}
  53
  54   callscope(name, pref, args)
  55
  56   can do losts ofthings
  57
  58    ?? classify me...
  59       foo = new (function() { }
  60      (function() { }
  61     RETURN function(...) {
  62
  63
  64
  65
  66
  67
  68
  69  *
  70  *
  71  * usage  :
  72  * sn = new ScopeName({
  73     tokens : ... result from tokenizer,
  74
  75  })
  76    sn.buildSymbols();
  77  *
  78  * @param {Array} tokens array of tokens (from collapse)
  79  * @param {String} srcFile the original file
  80  * @param {Array} args Local variables which do not need to be added to scope.
  81  */
  82
  83 ScopeNamer = XObject.define(
  84     function (cfg)
  85     {
  86
  87         ScopeNamer.superclass.constructor.call(this, cfg);
  88         this.args = this.args ? this.args.slice(0)  : [];
  89         Symbol.srcFile = this.filename;
  90         this.createJSDOC = true;
  91
  92        // console.dump(ar);
  93
  94     },
  95     imports.JSDOC.Collapse.Collapse,
  96     {
  97         /**
  98          * Call debugging
  99          * add/remove ';' after return to configure at present..
 100          * @param {String} str String to output
 101          */
 102         debugCall : function(str)  { return ; print(str); },
 103
 104         collapseTop : true,
 105
 106         buildSymbols : function()
 107         {
 108             if (!this.statements) {
 109                 this.statements = this.collapse(this.tokens);
 110                 //print(JSON.stringify(this.s, null,4));
 111             }
 112
 113             //this.globalScope(this.statements);
 114             this.debugCall("build Symbols");
 115             //print (this.statements);
 116             //print (JSON.stringify(this.statements, null,2));
 117
 118             this.walkStatements('_global_', this.statements)
 119
 120
 121
 122         },
 123
 124
 125         ignore : false,
 126
 127
 128
 129
 130         walkStatements: function(scope, statements)
 131         {
 132             this.debugCall("walkStatements :" + scope ) ;
 133             var _this = this;
 134             var res = false;
 135             var isGlobal = scope == '_global_';
 136
 137             statements.some(function(st ) {
 138
 139                 if (isGlobal &&
 140                         st[0].jsdoc &&
 141                         st[0].jsdoc.getTag('scope').length
 142                    ) {
 143
 144                     print("GOT scope");
 145                     print(st[0].jsdoc.getTag('scope'));
 146                  }
 147
 148
 149                 res = _this.walkStatement(scope, st);
 150                 if (res === true) {
 151                     return true;
 152                 }
 153                 return false;
 154             });
 155         },
 156
 157         walkStatement: function(scope, stmt)
 158         {
 159             this.tokens = stmt;
 160             this.rewind();
 161             this.debugCall("walkStatement :" + scope + '@' + this.tokens[0].line );
 162
 163             var name;
 164             var sn;
 165
 166             var isGlobal = scope == '_global_';
 167
 168
 169
 170             //if (this.filename.match(/pack\.js/) && isGlobal) {
 171             //    print(JSON.stringify(stmt , null,4));
 172             //}
 173             // @ignore stops the parser..
 174             if (isGlobal &&
 175                     stmt[0].jsdoc &&
 176                     stmt[0].jsdoc.getTag('ignore').length
 177                ) {
 178                 this.debugCall("walkStatement : ignore found - " + scope + '@' + this.tokens[0].line );
 179                 print("GOT ignore?");
 180                 return true;
 181             }
 182
 183
 184             while (null != (token = this.next())) {
 185
 186                 //'function'
 187                 //walkFunction(scope, name , args,  stmts  )
 188                 //
 189                 if (token.name == "FUNCTION") {
 190                     // function a() { .... } << scope is a  $this$={a}
 191                     if (this.lookTok(1).is('NAME')) {
 192                         name = isGlobal ? this.lookTok(1).data : '';
 193
 194                         this.walkFunctionDef(scope, name, this.lookTok(2).args, this.lookTok(3).items, token);
 195                         continue;
 196                     }
 197                      //a = function() { } << scope might be a  $this$={a}
 198                     if (this.lookTok(-1).data == '=' &&
 199                         this.lookTok(-2).is('NAME')
 200                     ) {
 201                         name = this.lookTok(-2).data;
 202                         this.walkFunctionDef(scope, name, this.lookTok(1).args, this.lookTok(2).items, this.lookTok(-2));
 203                         continue;
 204                     }
 205
 206
 207                     print("+++ FUNCTION unusual context" + token.file + ':' + token.line);
 208                     continue;
 209
 210                 }
 211
 212                 // control flow ...
 213
 214
 215
 216                 // 'call' scopes
 217                 // XX.yy(a,b, { .... }) << scope might be a or b..  $this$={a}
 218                 // aa = XX.yy(a,b, { .... }) << scope might aa   $this$={a}
 219
 220                 if (token.is('NAME') && this.lookTok(1).data =='(') {
 221                     var assign = false;
 222                     var jsdoc = token.jsdoc;
 223                     if ((this.lookTok(-1).data == '=') && this.lookTok(-2).is('NAME')) {
 224                         assign = this.lookTok(-2).data
 225                         jsdoc = jsdoc || this.lookTok(-2).jsdoc;
 226                     }
 227                     this.walkCall(scope, assign, token.data, this.lookTok(1).items, jsdoc);
 228                     continue;
 229                 }
 230
 231                 //  'object'
 232                 //   a = { .... } << scope is a  $this$={a}
 233                 if (token.data == '{' && this.lookTok(-1).data == '=' && this.lookTok(-2).is('NAME')) {
 234
 235                     // could be var x = ..
 236                     var jd = this.lookTok(-2).jsdoc ? this.lookTok(-2) : this.lookTok(-3);
 237
 238                     var isVar = this.lookTok(-3).name == 'VAR';
 239
 240                     // only register names of objects if
 241                     var name = this.lookTok(-2).data;
 242                     name = !isGlobal && isVar ? false : name;
 243                     name = !isGlobal && name && !name.match(/^this\./) ? false : name;
 244                     //print(JSON.stringify(token,null,4));
 245                     this.walkObject(scope, name, token.props, jd);
 246                     continue;
 247                 }
 248
 249                 // this.xxxx = (with jsdoc...)
 250
 251
 252
 253
 254                 // standard flow....
 255                 if (token.data == '{') {
 256                     sn = new ScopeNamer(this);
 257                     //print("GOT { - walkings statuements;}");
 258                     if (!token.items) {
 259                         continue; // object..!?!?!? = ignore ???
 260                         print(JSON.stringify(token,null,4));
 261                     }
 262                     sn.walkStatements(scope, token.items);
 263                     continue;
 264                 }
 265             }
 266         },
 267
 268         walkFunctionDef : function (inscope, name, args, stmts, jsdocTok)
 269         {
 270             this.debugCall("wallkFuncDef: " + inscope + '@' + this.look(0).line );
 271             var scope = name.length ? (inscope + '.' + name) : inscope;
 272             if (name.length) {
 273                 var symbol = new Symbol( scope , args || [] , "FUNCTION" ,  jsdocTok.jsdoc);
 274                 symbol._token = jsdocTok;
 275                 this.addSymbol(symbol, jsdocTok.jsdoc);
 276             }
 277             var sn = new ScopeNamer(this);
 278             sn.walkStatements(scope, stmts);
 279
 280         },
 281
 282
 283
 284         walkCall : function (inscope, assign, callname, items, jsdocTok)
 285         {
 286             this.debugCall("wallkCall : " + inscope  +':' + assign + '@' + this.look(0).line + ' ' + callname );
 287             var scope = inscope + ( assign ? ('.' + assign) : '' );
 288             //scope = scope.replace(/\^_global\$\./, '');
 289
 290
 291
 292
 293             // add the handers for differnt methods in here....
 294             switch (callname) {
 295
 296                 // somecall(BASE, { .. object ..})
 297                 // or... x = somecall(BASE, { ... object..})
 298                 case 'XObject.extend':
 299                 case 'Roo.apply':
 300                     //print(JSON.stringify(items,null,4));
 301                     scope = items[0][0].data;
 302                     // 2nd arg is a object def
 303                     if (items[1][0].data != '{') {
 304                         return;
 305                     }
 306
 307                     if (assign != false   && !scope.match(/\.prototype$/)) {
 308                         var symbol = new Symbol( scope , false , "OBJECT" ,  jsdocTok);
 309                         symbol._token = jsdocTok;
 310                         this.addSymbol(symbol, jsdocTok.jsdoc);
 311
 312                     }
 313
 314
 315                     var sn = new ScopeNamer(this);
 316
 317                     //print(JSON.stringify(items,null,4));
 318                     sn.walkObject(scope , false, items[1][0].props, jsdocTok );
 319
 320                     return;
 321
 322
 323
 324
 325                 case 'XObject.define':
 326                     // func, extends, props.
 327
 328                     var symbol = new Symbol( scope , items[0][1].args || [] , "CONSTRUCTOR" ,  jsdocTok);
 329                     symbol._token = jsdocTok;
 330                     // extends = arg[1]
 331
 332                     this.addSymbol(symbol, jsdocTok.jsdoc);
 333                     var sn = new ScopeNamer(this);
 334
 335
 336                     sn.walkStatements(scope, items[0][2].items);
 337                     sn.walkObject(scope + '.prototype', false, items[2].props );
 338                     return;
 339
 340
 341
 342             }
 343
 344
 345
 346         },
 347
 348         walkObject : function(inscope, name, items, jsdocTok)
 349         {
 350             var scope = inscope + (( name === false) ? '' : ('.' + name));
 351
 352             if (name !== false) {
 353
 354                 var symbol = new Symbol( scope , false , "OBJECT" ,  jsdocTok.jsdoc);
 355                 symbol._token = jsdocTok;
 356                 this.addSymbol(symbol, jsdocTok.jsdoc);
 357
 358             }
 359             // items can be false in this scenaro: a = {};
 360             if (!items) {
 361                 return;
 362             }
 363             print(typeof(items));
 364             this.debugCall("wallkObject : " + scope + '@' + items[Object.keys(items)[0]].key.line);
 365             for( var k in items) {
 366                 var key = items[k].key;
 367                 var val = items[k].val;
 368
 369
 370                 // x : function(....)
 371                 if (val[0].name == 'FUNCTION' ) {
 372
 373
 374                     this.walkFunctionDef (scope, k, val[1].args, val[2].items, key)
 375
 376
 377                     continue;
 378                 }
 379
 380                 // x: ( .... ) conditional  properties? maybe detect function?
 381
 382
 383                 // x : something else - not a function..
 384
 385
 386                 var symbol = new Symbol( scope +'.'+ k , val[1].args || [] , "PROPERTY" ,  key.jsdoc);
 387                 symbol._token = key;
 388
 389                 this.addSymbol(symbol, key.jsdoc);
 390                 continue;
 391
 392
 393             }
 394
 395
 396         },
 397
 398
 399
 400
 401
 402
 403         addSymbol: function(symbol, comment)
 404         {
 405               //print("ADD symbol: " + JSON.stringify( symbol, null, 4));
 406               //print("PARSER addSYMBOL : " + symbol.alias);
 407
 408             // if a symbol alias is documented more than once the last one with the user docs wins
 409
 410             // dumpe some invalid symbols..
 411             if (symbol.alias.split(/[#.]/).length > 2) {
 412                 return;
 413             }
 414             ScopeNamer.prototype.debugCall("addSymbol : " + symbol.alias );
 415
 416             if (ScopeNamer.symbols.hasSymbol(symbol.alias)) {
 417
 418                 if (!comment) { // we do not have a comment, and it's registered.
 419                     return;
 420                 }
 421                 var oldSymbol = ScopeNamer.symbols.getSymbol(symbol.alias);
 422
 423                 if (oldSymbol.comment && oldSymbol.comment.isUserComment && !oldSymbol.comment.hasTags) {
 424                     if (symbol.comment.isUserComment) { // old and new are both documented
 425                         this.LOG.warn("The symbol '"+symbol.alias+"' is documented more than once.");
 426                     }
 427                     else { // old is documented but new isn't
 428                         return;
 429                     }
 430                 }
 431             }
 432
 433             // we don't document anonymous things
 434             //if (this.conf.ignoreAnonymous && symbol.name.match(/\$anonymous\b/)) return;
 435
 436             // uderscored things may be treated as if they were marked private, this cascades
 437             //if (this.conf.treatUnderscoredAsPrivate && symbol.name.match(/[.#-]_[^.#-]+$/)) {
 438             //    symbol.isPrivate = true;
 439             //}
 440
 441             // -p flag is required to document private things
 442             if ((symbol.isInner || symbol.isPrivate) && !this.docPrivate) return;
 443
 444             // ignored things are not documented, this doesn't cascade
 445             if (symbol.isIgnored) return;
 446
 447
 448             //print("ADD symbol: " + symbol.isa + ' => ' + symbol.alias );
 449             //print("ADD symbol: " + JSON.stringify( symbol, null, 4));
 450
 451             // add it to the file's list... (for dumping later..)
 452             if (this.srcFile) {
 453                 ScopeNamer.filesSymbols[Symbol.srcFile].addSymbol(symbol);
 454             }
 455
 456             ScopeNamer.symbols.addSymbol(symbol);
 457         },
 458         addBuiltin : function(name) {
 459
 460             var builtin = new Symbol(name, [], "CONSTRUCTOR", new imports.DocComment.DocComment(""));
 461             builtin.isNamespace = false;
 462             builtin.srcFile = "";
 463             builtin.isPrivate = false;
 464             this.addSymbol(builtin);
 465             return builtin;
 466         }
 467
 468
 469
 470     }
 471 );
 472
 473 ScopeNamer.symbols =  new  imports.SymbolSet.SymbolSet();
 474
 475
 476
 477
 478
 479 ScopeNamer.addSymbol = ScopeNamer.prototype.addSymbol;
 480 ScopeNamer.addBuiltin = ScopeNamer.prototype.addBuiltin;