jsduck 3.11.2 → 4.0.beta

data/lib/jsduck/options.rb

@@ -12,7 +12,6 @@ module JsDuck
     attr_accessor :output_dir
     attr_accessor :ignore_global
     attr_accessor :external_classes
-    attr_accessor :ext4_events
 
     # Customizing output
     attr_accessor :title
@@ -74,14 +73,13 @@ module JsDuck
         # Special anything-goes type
         "Mixed",
       ]
-      @ext4_events = nil
       @meta_tag_paths = []
 
-      @version = "3.11.2"
+      @version = "4.0.beta"
 
       # Customizing output
-      @title = "Ext JS - Sencha Docs"
-      @header = "<strong>Ext JS</strong> Sencha Docs"
+      @title = "Sencha Docs - Ext JS"
+      @header = "<strong>Sencha Docs</strong> Ext JS"
       @footer = "Generated with <a href='https://github.com/senchalabs/jsduck'>JSDuck</a> #{@version}."
       @head_html = ""
       @body_html = ""
@@ -159,14 +157,6 @@ module JsDuck
           @external_classes += classes
         end
 
-        opts.on('--[no-]ext4-events',
-          "Appends extra options parameter that all Ext events have.",
-          "The default is to auto-detect if we're using Ext JS 4",
-          "based on whether the code uses Ext.define.",
-          "Use this option to override the auto-detection.", " ") do |e|
-          @ext4_events = e
-        end
-
         opts.on('--builtin-classes',
           "Includes docs for JavaScript builtin classes.", " ") do
           read_filenames(@root_dir + "/js-classes")
@@ -191,7 +181,7 @@ module JsDuck
 
         opts.on('--title=TEXT',
           "Custom title text for the documentation.",
-          "Defaults to 'Ext JS - Sencha Docs'", " ") do |text|
+          "Defaults to 'Sencha Docs - Ext JS'", " ") do |text|
           @title = text
           @header = text.sub(/^(.*?) +- +/, "<strong>\\1 </strong>")
         end

data/lib/jsduck/serializer.rb

@@ -0,0 +1,262 @@
+module JsDuck
+
+  # Transforms Esprima AST into string
+  class Serializer
+
+    # Turns AST node into string
+    def to_s(ast)
+      case ast["type"]
+      when "Program"
+        ast["body"].map {|s| to_s(s) }.join
+
+      # Statements
+
+      when "BlockStatement"
+        "{" + ast["body"].map {|s| to_s(s) }.join + "}"
+
+      when "BreakStatement"
+        "break" + (ast["label"] ? " " + to_s(ast["label"]) : "") + ";"
+
+      when "ContinueStatement"
+        "continue" + (ast["label"] ? " " + to_s(ast["label"]) : "") + ";"
+
+      when "DoWhileStatement"
+        "do " + to_s(ast["body"]) + " while (" + to_s(ast["test"]) + ");"
+
+      when "DebuggerStatement"
+        "debugger;"
+
+      when "EmptyStatement"
+        ";"
+
+      when "ExpressionStatement"
+        to_s(ast["expression"]) + ";"
+
+      when "ForStatement"
+        init = ast["init"] ? to_s(ast["init"]).sub(/;\Z/, "") : ""
+        test = ast["test"] ? to_s(ast["test"]) : ""
+        update = ast["update"] ? to_s(ast["update"]) : ""
+        "for (" + init + "; " + test + "; " + update + ") " + to_s(ast["body"])
+
+      when "ForInStatement"
+        left = to_s(ast["left"]).sub(/;\Z/, "")
+        right = to_s(ast["right"])
+        "for (" + left + " in " + right + ") " + to_s(ast["body"])
+
+      when "IfStatement"
+        alternate = ast["alternate"] ? " else " + to_s(ast["alternate"]) : ""
+        "if (" + to_s(ast["test"]) + ") " + to_s(ast["consequent"]) + alternate
+
+      when "LabeledStatement"
+        to_s(ast["label"]) + ": " + to_s(ast["body"])
+
+      when "ReturnStatement"
+        arg = ast["argument"] ? to_s(ast["argument"]) : ""
+        "return " + arg + ";"
+
+      when "SwitchStatement"
+        "switch (" + to_s(ast["discriminant"]) + ") {" + ast["cases"].map {|c| to_s(c) }.join + "}"
+
+      when "SwitchCase"
+        test = ast["test"] ? "case " + to_s(ast["test"]) : "default"
+        test + ": " + ast["consequent"].map {|c| to_s(c) }.join
+
+      when "ThrowStatement"
+        "throw " + to_s(ast["argument"]) + ";"
+
+      when "TryStatement"
+        handlers = ast["handlers"].map {|h| to_s(h) }.join
+        finalizer = ast["finalizer"] ? " finally " + to_s(ast["finalizer"]) : ""
+        "try " + to_s(ast["block"]) + handlers + finalizer
+
+      when "CatchClause"
+        param = ast["param"] ? to_s(ast["param"]) : ""
+        " catch (" + param + ") " + to_s(ast["body"])
+
+      when "WhileStatement"
+        "while (" + to_s(ast["test"]) + ") " + to_s(ast["body"])
+
+      when "WithStatement"
+        "with (" + to_s(ast["object"]) + ") " + to_s(ast["body"])
+
+
+      # Declarations
+
+      when "FunctionDeclaration"
+        function(ast)
+
+      when "VariableDeclaration"
+        ast["kind"] + " " + list(ast["declarations"]) + ";"
+
+      when "VariableDeclarator"
+        if ast["init"]
+          to_s(ast["id"]) + " = " + to_s(ast["init"])
+        else
+          to_s(ast["id"])
+        end
+
+      # Expressions
+
+      when "AssignmentExpression"
+        parens(ast, ast["left"]) + " " + ast["operator"] + " " + to_s(ast["right"])
+
+      when "ArrayExpression"
+        "[" + list(ast["elements"]) + "]"
+
+      when "BinaryExpression"
+        binary(ast)
+
+      when "CallExpression"
+        call(ast)
+
+      when "ConditionalExpression"
+        parens(ast, ast["test"]) + " ? " + to_s(ast["consequent"]) + " : " + to_s(ast["alternate"])
+
+      when "FunctionExpression"
+        function(ast)
+
+      when "LogicalExpression"
+        binary(ast)
+
+      when "MemberExpression"
+        if ast["computed"]
+          parens(ast, ast["object"]) + "[" + to_s(ast["property"]) + "]"
+        else
+          parens(ast, ast["object"]) + "." + to_s(ast["property"])
+        end
+
+      when "NewExpression"
+        "new " + call(ast)
+
+      when "ObjectExpression"
+        "{" + list(ast["properties"]) + "}"
+
+      when "Property"
+        to_s(ast["key"]) + ": " + to_s(ast["value"])
+
+      when "SequenceExpression"
+        list(ast["expressions"])
+
+      when "ThisExpression"
+        "this"
+
+      when "UnaryExpression"
+        ast["operator"] + parens(ast, ast["argument"])
+
+      when "UpdateExpression"
+        if ast["prefix"]
+          ast["operator"] + parens(ast, ast["argument"])
+        else
+          parens(ast, ast["argument"]) + ast["operator"]
+        end
+
+      # Basics
+
+      when "Identifier"
+        ast["name"]
+
+      when "Literal"
+        ast["raw"]
+
+      else
+        throw "Unknown node type: "+ast["type"]
+      end
+    end
+
+    private
+
+    # serializes function declaration or expression
+    def function(ast)
+      params = list(ast["params"])
+      id = ast["id"] ? to_s(ast["id"]) : ""
+      "function " + id + "(" + params + ") " + to_s(ast["body"])
+    end
+
+    # serializes list of comma-separated items
+    def list(array)
+      array.map {|x| to_s(x) }.join(", ")
+    end
+
+    # serializes call- and new-expression
+    def call(ast)
+      parens(ast, ast["callee"]) + "(" + list(ast["arguments"]) + ")"
+    end
+
+    # Handles both binary- and logical-expression
+    def binary(ast)
+      parens(ast, ast["left"]) + " " + ast["operator"] + " " + parens(ast, ast["right"])
+    end
+
+    # serializes child node and wraps it inside parenthesis if the
+    # precedence rules compared to parent node would require so.
+    def parens(parent, child)
+      if precedence(parent) >= precedence(child)
+        to_s(child)
+      else
+        "(" + to_s(child) + ")"
+      end
+    end
+
+    # Returns the precedence of operator represented by given AST node
+    def precedence(ast)
+      p = PRECEDENCE[ast["type"]]
+      if p.is_a? Fixnum
+        p
+      elsif p.is_a? Hash
+        p[ast["operator"]]
+      else
+        0
+      end
+    end
+
+    # Precedence rules of JavaScript operators.
+    #
+    # Taken from: https://developer.mozilla.org/en/JavaScript/Reference/Operators/Operator_Precedence
+    #
+    PRECEDENCE = {
+      "SequenceExpression" => 17,
+      "AssignmentExpression" => 16,
+      "ConditionalExpression" => 15,
+      "LogicalExpression" => {
+        "||" => 14,
+        "&&" => 13,
+      },
+      "BinaryExpression" => {
+        "|" => 12,
+        "^" => 11,
+        "&" => 10,
+
+        "==" => 9,
+        "!=" => 9,
+        "===" => 9,
+        "!==" => 9,
+
+        "<" => 8,
+        "<=" => 8,
+        ">" => 8,
+        ">=" => 8,
+        "in" => 8,
+        "instanceof" => 8,
+
+        "<<" => 7,
+        ">>" => 7,
+        ">>>" => 7,
+
+        "+" => 6,
+        "-" => 6,
+
+        "*" => 5,
+        "/" => 5,
+        "%" => 5,
+      },
+      "UnaryExpression" => 4,
+      "UpdateExpression" => 3,
+      "CallExpression" => 2,
+      "MemberExpression" => 1,
+      "NewExpression" => 1,
+    }
+
+  end
+
+end
+

data/lib/jsduck/source_file.rb

@@ -1,6 +1,4 @@
-require 'jsduck/js_parser'
-require 'jsduck/css_parser'
-require 'jsduck/merger'
+require 'jsduck/source_file_parser'
 require 'jsduck/html'
 
 module JsDuck
@@ -18,15 +16,13 @@ module JsDuck
     def initialize(contents, filename="", options={})
       @contents = contents
       @filename = filename
-      @options = options
       @html_filename = ""
       @links = {}
 
-      merger = Merger.new
-      merger.filename = @filename
-      @docs = parse.map do |docset|
-        merger.linenr = docset[:linenr]
-        link(docset[:linenr], merger.merge(docset[:comment], docset[:code]))
+      @docs = SourceFileParser.instance.parse(@contents, @filename, options)
+
+      @docs.map do |docset|
+        link(docset[:linenr], docset)
       end
     end
 
@@ -78,15 +74,6 @@ module JsDuck
 
     private
 
-    # Parses the file depending on filename as JS or CSS
-    def parse
-      if @filename =~ /\.s?css$/
-        CssParser.new(@contents, @options).parse
-      else
-        JsParser.new(@contents, @options).parse
-      end
-    end
-
     # Creates two-way link between sourcefile and doc-object.
     # If doc-object is class, links also the contained cfgs and constructor.
     # Returns the modified doc-object after done.

data/lib/jsduck/source_file_parser.rb

@@ -0,0 +1,72 @@
+require 'singleton'
+require 'jsduck/js_parser'
+require 'jsduck/css_parser'
+require 'jsduck/doc_parser'
+require 'jsduck/merger'
+require 'jsduck/ast'
+require 'jsduck/doc_type'
+require 'jsduck/doc_ast'
+require 'jsduck/class_doc_expander'
+
+module JsDuck
+
+  # Performs the actual parsing of CSS or JS source.
+  #
+  # This is the class that brings together all the different steps of
+  # parsing the source.
+  class SourceFileParser
+    include Singleton
+
+    def initialize
+      @doc_type = DocType.new
+      @doc_parser = DocParser.new
+      @class_doc_expander = ClassDocExpander.new
+      @doc_ast = DocAst.new
+      @merger = Merger.new
+    end
+
+    # Parses file into final docset that can be fed into Aggregator
+    def parse(contents, filename="", options={})
+      @doc_ast.filename = filename
+
+      parse_js_or_css(contents, filename, options).map do |docset|
+        expand(docset)
+      end.flatten.map do |docset|
+        merge(docset)
+      end
+    end
+
+    private
+
+    # Parses the file depending on filename as JS or CSS
+    def parse_js_or_css(contents, filename, options)
+      if filename =~ /\.s?css$/
+        docs = CssParser.new(contents, options).parse
+      else
+        docs = JsParser.new(contents, options).parse
+        docs = Ast.new(docs, options).detect_all!
+      end
+    end
+
+    # Parses the docs, detects tagname and expands class docset
+    def expand(docset)
+      docset[:comment] = @doc_parser.parse(docset[:comment])
+      docset[:tagname] = @doc_type.detect(docset[:comment], docset[:code])
+
+      if docset[:tagname] == :class
+        @class_doc_expander.expand(docset)
+      else
+        docset
+      end
+    end
+
+    # Merges comment and code parts of docset
+    def merge(docset)
+      @doc_ast.linenr = docset[:linenr]
+      docset[:comment] = @doc_ast.detect(docset[:tagname], docset[:comment])
+
+      @merger.merge(docset)
+    end
+  end
+
+end

metadata

@@ -1,8 +1,8 @@
 --- !ruby/object:Gem::Specification
 name: jsduck
 version: !ruby/object:Gem::Version
-  version: 3.11.2
-  prerelease: 
+  version: 4.0.beta
+  prerelease: 4
 platform: ruby
 authors:
 - Rene Saarsoo
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-07 00:00:00.000000000 Z
+date: 2012-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdiscount
@@ -60,6 +60,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: execjs
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -117,6 +133,8 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - COPYING
+- Gemfile
+- Gemfile.lock
 - README.md
 - Rakefile
 - bin/compare
@@ -137,15 +155,21 @@ files:
 - lib/jsduck/app_data.rb
 - lib/jsduck/app_exporter.rb
 - lib/jsduck/assets.rb
+- lib/jsduck/ast.rb
 - lib/jsduck/auto_categories.rb
 - lib/jsduck/categories.rb
 - lib/jsduck/class.rb
+- lib/jsduck/class_doc_expander.rb
 - lib/jsduck/class_formatter.rb
 - lib/jsduck/class_writer.rb
 - lib/jsduck/css_lexer.rb
 - lib/jsduck/css_parser.rb
+- lib/jsduck/doc_ast.rb
 - lib/jsduck/doc_formatter.rb
 - lib/jsduck/doc_parser.rb
+- lib/jsduck/doc_type.rb
+- lib/jsduck/esprima.rb
+- lib/jsduck/evaluator.rb
 - lib/jsduck/examples.rb
 - lib/jsduck/examples_exporter.rb
 - lib/jsduck/file_categories.rb
@@ -162,8 +186,6 @@ files:
 - lib/jsduck/inline_img.rb
 - lib/jsduck/inline_video.rb
 - lib/jsduck/io.rb
-- lib/jsduck/js_literal_builder.rb
-- lib/jsduck/js_literal_parser.rb
 - lib/jsduck/js_parser.rb
 - lib/jsduck/json_duck.rb
 - lib/jsduck/lexer.rb
@@ -180,14 +202,15 @@ files:
 - lib/jsduck/relations.rb
 - lib/jsduck/renderer.rb
 - lib/jsduck/search_data.rb
+- lib/jsduck/serializer.rb
 - lib/jsduck/source_file.rb
+- lib/jsduck/source_file_parser.rb
 - lib/jsduck/source_writer.rb
 - lib/jsduck/stats.rb
 - lib/jsduck/stdout.rb
 - lib/jsduck/tag/abstract.rb
 - lib/jsduck/tag/aside.rb
 - lib/jsduck/tag/author.rb
-- lib/jsduck/tag/chainable.rb
 - lib/jsduck/tag/deprecated.rb
 - lib/jsduck/tag/docauthor.rb
 - lib/jsduck/tag/hide.rb
@@ -639,6 +662,7 @@ files:
 - template-min/extjs/ext-all.js
 - template-min/build-js.html
 - template-min/index.php
+- esprima/esprima.js
 homepage: https://github.com/senchalabs/jsduck
 licenses: []
 post_install_message: 
@@ -654,12 +678,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>='
+  - - ! '>'
     - !ruby/object:Gem::Version
-      version: 1.3.5
+      version: 1.3.1
 requirements: []
 rubyforge_project: jsduck
-rubygems_version: 1.8.24
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Simple JavaScript Duckumentation generator