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

http://jsdoc-toolkit.googlecode.com/ · JavaScript · 109 lines · 77 code · 19 blank · 13 comment · 28 complexity · 6c480d6e355abda7ed2294215f6a56ed 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 a symbol alias is documented more than once the last one with the user docs wins
  17. if (JSDOC.Parser.symbols.hasSymbol(symbol.alias)) {
  18. var oldSymbol = JSDOC.Parser.symbols.getSymbol(symbol.alias);
  19. if (oldSymbol.comment.isUserComment) {
  20. if (symbol.comment.isUserComment) { // old and new are both documented
  21. LOG.warn("The symbol '"+symbol.alias+"' is documented more than once.");
  22. }
  23. else { // old is documented but new isn't
  24. return;
  25. }
  26. }
  27. }
  28. // we don't document anonymous things
  29. if (JSDOC.Parser.conf.ignoreAnonymous && symbol.name.match(/\$anonymous\b/)) return;
  30. // uderscored things may be treated as if they were marked private, this cascades
  31. if (JSDOC.Parser.conf.treatUnderscoredAsPrivate && symbol.name.match(/[.#-]_[^.#-]+$/)) {
  32. symbol.isPrivate = true;
  33. }
  34. // -p flag is required to document private things
  35. if ((symbol.isInner || symbol.isPrivate) && !JSDOC.opt.p) return;
  36. // ignored things are not documented, this doesn't cascade
  37. if (symbol.isIgnored) return;
  38. JSDOC.Parser.symbols.addSymbol(symbol);
  39. },
  40. addBuiltin: function(name) {
  41. var builtin = new JSDOC.Symbol(name, [], "CONSTRUCTOR", new JSDOC.DocComment(""));
  42. builtin.isNamespace = true;
  43. builtin.srcFile = "";
  44. builtin.isPrivate = false;
  45. JSDOC.Parser.addSymbol(builtin);
  46. return builtin;
  47. },
  48. init: function() {
  49. JSDOC.Parser.symbols = new JSDOC.SymbolSet();
  50. JSDOC.Parser.walker = new JSDOC.Walker();
  51. },
  52. finish: function() {
  53. JSDOC.Parser.symbols.relate();
  54. // make a litle report about what was found
  55. if (JSDOC.Parser.conf.explain) {
  56. var symbols = JSDOC.Parser.symbols.toArray();
  57. var srcFile = "";
  58. for (var i = 0, l = symbols.length; i < l; i++) {
  59. var symbol = symbols[i];
  60. if (srcFile != symbol.srcFile) {
  61. srcFile = symbol.srcFile;
  62. print("\n"+srcFile+"\n-------------------");
  63. }
  64. 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);
  65. }
  66. print("-------------------\n");
  67. }
  68. }
  69. }
  70. JSDOC.Parser.parse = function(/**JSDOC.TokenStream*/ts, /**String*/srcFile) {
  71. JSDOC.Symbol.srcFile = (srcFile || "");
  72. JSDOC.DocComment.shared = ""; // shared comments don't cross file boundaries
  73. if (!JSDOC.Parser.walker) JSDOC.Parser.init();
  74. JSDOC.Parser.walker.walk(ts); // adds to our symbols
  75. // filter symbols by option
  76. for (p in JSDOC.Parser.symbols._index) {
  77. var symbol = JSDOC.Parser.symbols.getSymbol(p);
  78. if (!symbol) continue;
  79. if (symbol.is("FILE") || symbol.is("GLOBAL")) {
  80. continue;
  81. }
  82. else if (!JSDOC.opt.a && !symbol.comment.isUserComment) {
  83. JSDOC.Parser.symbols.deleteSymbol(symbol.alias);
  84. }
  85. if (/#$/.test(symbol.alias)) { // we don't document prototypes
  86. JSDOC.Parser.symbols.deleteSymbol(symbol.alias);
  87. }
  88. }
  89. return JSDOC.Parser.symbols.toArray();
  90. }