/tags/jsdoc_toolkit-2.2.1/jsdoc-toolkit/app/lib/JSDOC/Parser.js

http://jsdoc-toolkit.googlecode.com/ · JavaScript · 145 lines · 110 code · 21 blank · 14 comment · 42 complexity · 656241e97d3e9eba05483ba2f43a2844 MD5 · raw file

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