jsduck 3.11.2 → 4.0.beta

data/.gitignore

@@ -3,4 +3,5 @@ template/extjs
 template/resources/css
 template/resources/sass/.sass-cache
 template-min/
+esprima/
 sdk-vars.rb

data/Gemfile

@@ -0,0 +1,4 @@
+source :rubygems
+
+gemspec
+

data/Gemfile.lock

@@ -0,0 +1,45 @@
+PATH
+  remote: .
+  specs:
+    jsduck (3.11.0)
+      execjs
+      json
+      parallel
+      rdiscount
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    chunky_png (1.2.5)
+    compass (0.12.2)
+      chunky_png (~> 1.2)
+      fssm (>= 0.2.7)
+      sass (~> 3.1)
+    diff-lcs (1.1.3)
+    execjs (1.4.0)
+      multi_json (~> 1.0)
+    fssm (0.2.9)
+    json (1.7.3)
+    multi_json (1.3.6)
+    parallel (0.5.17)
+    rake (0.9.2.2)
+    rdiscount (1.6.8)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.1)
+    rspec-expectations (2.10.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.10.1)
+    sass (3.1.19)
+
+PLATFORMS
+  ruby
+  x86-mingw32
+
+DEPENDENCIES
+  compass
+  jsduck!
+  rake
+  rspec

data/README.md

@@ -41,10 +41,7 @@ For **Windows** users out there, you can download the binary version,
 which includes Ruby interpreter and all dependencies bundled in a
 single .exe file.  Grab it from the [download page][].
 
-If you are brave enough: [try out JSDuck 4.0 beta.][beta]
-
 [download page]: https://github.com/senchalabs/jsduck/downloads
-[beta]: https://github.com/senchalabs/jsduck/wiki/4.0-beta
 
 Usage
 -----

data/Rakefile

@@ -220,6 +220,7 @@ task :ext4 => :sass do
   runner = JsDuckRunner.new
   runner.add_ext4
   runner.add_debug
+  runner.add_options("--tests")
   runner.run
 
   system("cp -r #{EXT_BUILD} #{OUT_DIR}/extjs-build")
@@ -232,7 +233,8 @@ task :sdk => :sass do
     "--output", OUT_DIR,
     "--config", "#{SDK_DIR}/extjs/docs/config.json",
     "--examples-base-url", "extjs-build/examples/",
-    "--seo"
+    "--seo",
+    "--tests"
   )
   runner.add_debug
   runner.add_comments('ext-js', '4')
@@ -248,7 +250,8 @@ task :touch2 => :sass do
     "--output", OUT_DIR,
     "--config", "#{SDK_DIR}/touch/docs/config.json",
     "--examples-base-url", "touch-build/examples/production/",
-    "--seo"
+    "--seo",
+    "--tests"
   )
 
   runner.add_debug

data/js-classes/String.js

@@ -949,7 +949,7 @@
  *
  * The following example displays the string "sencha":
  *
- *     var upperText="SENCHA";
+ *     var upperText="sencha";
  *     document.write(upperText.toLocaleLowerCase());
  *
  * @return {String} Returns value of the string in lowercase.

data/jsduck.gemspec

@@ -2,8 +2,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = ">= 1.3.5"
 
   s.name = 'jsduck'
-  s.version = '3.11.2'
-  s.date = '2012-08-07'
+  s.version = '4.0.beta'
+  s.date = '2012-06-27'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for Sencha JS frameworks"
   s.homepage = "https://github.com/senchalabs/jsduck"
@@ -16,12 +16,15 @@ Gem::Specification.new do |s|
   end
   # Add files not in git
   s.files += Dir['template-min/**/*']
+  # Add Esprima
+  s.files += Dir['esprima/esprima.js']
 
   s.executables = ["jsduck"]
 
   s.add_dependency 'rdiscount'
   s.add_dependency 'json'
   s.add_dependency 'parallel'
+  s.add_dependency 'execjs'
 
   s.add_development_dependency 'rspec'
   s.add_development_dependency 'rake'

data/lib/jsduck/accessors.rb

@@ -110,6 +110,7 @@ module JsDuck
         :owner => cfg[:owner],
         :files => cfg[:files],
         :private => cfg[:private],
+        :autodetected => cfg[:autodetected],
         :meta => clone_meta(cfg),
       })
     end

data/lib/jsduck/aggregator.rb

@@ -205,7 +205,10 @@ module JsDuck
     end
 
     # Appends Ext4 options parameter to each event parameter list.
+    # But only when we are dealing with Ext4 codebase.
     def append_ext4_event_options
+      return unless ext4?
+
       options = {
         :tagname => :param,
         :name => "eOpts",

data/lib/jsduck/app.rb

@@ -124,9 +124,7 @@ module JsDuck
       agr.create_global_class
       agr.remove_ignored_classes
       agr.create_accessors
-      if @opts.ext4_events == true || (@opts.ext4_events == nil && agr.ext4?)
-        agr.append_ext4_event_options
-      end
+      agr.append_ext4_event_options
       agr.result
     end
 
@@ -165,15 +163,14 @@ module JsDuck
       class_formatter.include_types = !@opts.export
       # Format all doc-objects in parallel
       formatted_classes = @parallel.map(@relations.classes) do |cls|
-        files = cls[:files].map {|f| f[:filename] }.join(" ")
-        Logger.instance.log("Markdown formatting #{cls[:name]}", files)
+        Logger.instance.log("Markdown formatting #{cls[:name]}")
         begin
           {
             :doc => class_formatter.format(cls.internal_doc),
             :images => doc_formatter.images
           }
         rescue
-          Logger.instance.fatal("Error while formatting #{cls[:name]} #{files}", $!)
+          Logger.instance.fatal("Error while formatting #{cls[:name]}", $!)
           exit(1)
         end
       end

data/lib/jsduck/ast.rb

@@ -0,0 +1,446 @@
+require "jsduck/serializer"
+require "jsduck/evaluator"
+
+module JsDuck
+
+  # Analyzes the AST produced by EsprimaParser.
+  class Ast
+    # Should be initialized with EsprimaParser#parse result.
+    def initialize(docs = [], options = {})
+      @serializer = JsDuck::Serializer.new
+      @evaluator = JsDuck::Evaluator.new
+      @ext_define_patterns = build_ext_define_patterns(options[:ext_namespaces] || ["Ext"])
+      @docs = docs
+    end
+
+    # Given Array of alternate Ext namespaces builds list of patterns
+    # for detecting Ext.define:
+    #
+    # ["Ext","Foo"] --> ["Ext.define", "Ext.ClassManager.create", "Foo.define", "Foo.ClassManager.create"]
+    #
+    def build_ext_define_patterns(namespaces)
+      namespaces.map do |ns|
+        [ns + ".define", ns + ".ClassManager.create"]
+      end.flatten
+    end
+
+    # Performs the detection of code in all docsets.
+    #
+    # @returns the processed array of docsets. (But it does it
+    # destructively by modifying the passed-in docsets.)
+    #
+    def detect_all!
+      # First deal only with doc-comments
+      doc_comments = @docs.find_all {|d| d[:type] == :doc_comment }
+
+      # Detect code in each docset.  Sometimes a docset has already
+      # been detected as part of detecting some previous docset (like
+      # Class detecting all of its configs) - in such case, skip.
+      doc_comments.each do |docset|
+        code = docset[:code]
+        docset[:code] = detect(code) unless code && code[:tagname]
+      end
+
+      # Return all doc-comments + other comments for which related
+      # code was detected.
+      @docs.find_all {|d| d[:type] == :doc_comment || d[:code] && d[:code][:tagname] }
+    end
+
+    # Given Esprima-produced syntax tree, detects documentation data.
+    #
+    # This method is exposed for testing purposes only, JSDuck itself
+    # only calls the above #detect_all method.
+    #
+    # @param ast :code from Result of EsprimaParser
+    # @returns Hash consisting of the detected :tagname, :name, and
+    # other properties relative to the tag.  Like so:
+    #
+    #     { :tagname => :method, :name => "foo", ... }
+    #
+    def detect(ast)
+      ast = ast || {}
+
+      exp = expression?(ast) ? ast["expression"] : nil
+      var = var?(ast) ? ast["declarations"][0] : nil
+
+      # Ext.define("Class", {})
+      if exp && ext_define?(exp)
+        make_class(to_value(exp["arguments"][0]), exp)
+
+      # foo = Ext.extend("Parent", {})
+      elsif exp && assignment?(exp) && ext_extend?(exp["right"])
+        make_class(to_s(exp["left"]), exp["right"])
+
+      # Foo = ...
+      elsif exp && assignment?(exp) && class_name?(to_s(exp["left"]))
+        make_class(to_s(exp["left"]))
+
+      # var foo = Ext.extend("Parent", {})
+      elsif var && var["init"] && ext_extend?(var["init"])
+        make_class(to_s(var["id"]), var["init"])
+
+      # var Foo = ...
+      elsif var && class_name?(to_s(var["id"]))
+        make_class(to_s(var["id"]))
+
+      # function Foo() {}
+      elsif function?(ast) && class_name?(to_s(ast["id"]))
+        make_class(to_s(ast["id"]))
+
+      # function foo() {}
+      elsif function?(ast)
+        make_method(to_s(ast["id"]), ast)
+
+      # foo = function() {}
+      elsif exp && assignment?(exp) && function?(exp["right"])
+        make_method(to_s(exp["left"]), exp["right"])
+
+      # var foo = function() {}
+      elsif var && var["init"] && function?(var["init"])
+        make_method(to_s(var["id"]), var["init"])
+
+      # (function() {})
+      elsif exp && function?(exp)
+        make_method(exp["id"] ? to_s(exp["id"]) : "", exp)
+
+      # foo: function() {}
+      elsif property?(ast) && function?(ast["value"])
+        make_method(key_value(ast["key"]), ast["value"])
+
+      # foo = ...
+      elsif exp && assignment?(exp)
+        make_property(to_s(exp["left"]), exp["right"])
+
+      # var foo = ...
+      elsif var
+        make_property(to_s(var["id"]), var["init"])
+
+      # foo: ...
+      elsif property?(ast)
+        make_property(key_value(ast["key"]), ast["value"])
+
+      # foo;
+      elsif exp && ident?(exp)
+        make_property(to_s(exp))
+
+      # "foo"  (inside some expression)
+      elsif string?(ast)
+        make_property(to_value(ast))
+
+      # "foo";  (as a statement of it's own)
+      elsif exp && string?(exp)
+        make_property(to_value(exp))
+
+      else
+        make_property()
+      end
+    end
+
+    private
+
+    def expression?(ast)
+      ast["type"] == "ExpressionStatement"
+    end
+
+    def call?(ast)
+      ast["type"] == "CallExpression"
+    end
+
+    def assignment?(ast)
+      ast["type"] == "AssignmentExpression"
+    end
+
+    def ext_define?(ast)
+      call?(ast) && @ext_define_patterns.include?(to_s(ast["callee"]))
+    end
+
+    def ext_extend?(ast)
+      call?(ast) && to_s(ast["callee"]) == "Ext.extend"
+    end
+
+    def function?(ast)
+      ast["type"] == "FunctionDeclaration" || ast["type"] == "FunctionExpression" || empty_fn?(ast)
+    end
+
+    def empty_fn?(ast)
+      ast["type"] == "MemberExpression" && to_s(ast) == "Ext.emptyFn"
+    end
+
+    def var?(ast)
+      ast["type"] == "VariableDeclaration"
+    end
+
+    def property?(ast)
+      ast["type"] == "Property"
+    end
+
+    def ident?(ast)
+      ast["type"] == "Identifier"
+    end
+
+    def string?(ast)
+      ast["type"] == "Literal" && ast["value"].is_a?(String)
+    end
+
+    # Class name begins with upcase char
+    def class_name?(name)
+      return name.split(/\./).last =~ /\A[A-Z]/
+    end
+
+    def make_class(name, ast=nil)
+      cls = {
+        :tagname => :class,
+        :name => name,
+      }
+
+      # apply information from Ext.extend or Ext.define
+      if ast
+        if ext_extend?(ast)
+          cls[:extends] = to_s(ast["arguments"][0])
+        elsif ext_define?(ast)
+          detect_ext_define(cls, ast)
+        end
+      end
+
+      return cls
+    end
+
+    # Inspects Ext.define() and copies detected properties over to the
+    # given cls Hash
+    def detect_ext_define(cls, ast)
+      # defaults
+      cls[:extends] = "Ext.Base"
+      cls[:requires] = []
+      cls[:uses] = []
+      cls[:alternateClassNames] = []
+      cls[:mixins] = []
+      cls[:aliases] = []
+      cls[:members] = []
+      cls[:statics] = []
+
+      each_pair_in_object_expression(ast["arguments"][1]) do |key, value, pair|
+        case key
+        when "extend"
+          cls[:extends] = make_extends(value)
+        when "requires"
+          cls[:requires] = make_string_list(value)
+        when "uses"
+          cls[:uses] = make_string_list(value)
+        when "alternateClassName"
+          cls[:alternateClassNames] = make_string_list(value)
+        when "mixins"
+          cls[:mixins] = make_mixins(value)
+        when "singleton"
+          cls[:singleton] = make_singleton(value)
+        when "alias"
+          cls[:aliases] += make_string_list(value)
+        when "xtype"
+          cls[:aliases] += make_string_list(value).map {|xtype| "widget."+xtype }
+        when "config"
+          cls[:members] += make_configs(value, {:accessor => true})
+        when "cachedConfig"
+          cls[:members] += make_configs(value, {:accessor => true})
+        when "eventedConfig"
+          cls[:members] += make_configs(value, {:accessor => true, :evented => true})
+        when "statics"
+          cls[:statics] += make_statics(value)
+        when "inheritableStatics"
+          cls[:statics] += make_statics(value, {:inheritable => true})
+        else
+          if function?(value)
+            m = make_method(key, value)
+            cls[:members] << m if apply_autodetected(m, pair)
+          else
+            p = make_property(key, value)
+            cls[:members] << p if apply_autodetected(p, pair)
+          end
+        end
+      end
+    end
+
+    def make_extends(cfg_value)
+      return nil unless cfg_value
+
+      parent = to_value(cfg_value)
+
+      return parent.is_a?(String) ? parent : nil
+    end
+
+    def make_string_list(cfg_value)
+      return [] unless cfg_value
+
+      classes = Array(to_value(cfg_value))
+
+      return classes.all? {|c| c.is_a? String } ? classes : []
+    end
+
+    def make_mixins(cfg_value)
+      return [] unless cfg_value
+
+      v = to_value(cfg_value)
+      classes = v.is_a?(Hash) ? v.values : Array(v)
+
+      return classes.all? {|c| c.is_a? String } ? classes : []
+    end
+
+    def make_singleton(cfg_value)
+      cfg_value && to_value(cfg_value) == true
+    end
+
+    def make_configs(ast, defaults={})
+      configs = []
+
+      each_pair_in_object_expression(ast) do |name, value, pair|
+        cfg = make_property(name, value, :cfg)
+        cfg.merge!(defaults)
+        configs << cfg if apply_autodetected(cfg, pair)
+      end
+
+      configs
+    end
+
+    def make_statics(ast, defaults={})
+      statics = []
+
+      each_pair_in_object_expression(ast) do |name, value, pair|
+        if function?(value)
+          s = make_method(name, value)
+        else
+          s = make_property(name, value)
+        end
+
+        s[:meta] = {:static => true}
+        s.merge!(defaults)
+
+        statics << s if apply_autodetected(s, pair, defaults[:inheritable])
+      end
+
+      statics
+    end
+
+    # Sets auto-detection related properties :autodetected and
+    # :inheritdoc on the given member Hash.
+    #
+    # When member has a comment, adds code to the related docset and
+    # returns false.
+    #
+    # Otherwise detects the line number of member and returns true.
+    def apply_autodetected(m, pair, inheritable=true)
+      docset = find_docset(pair)
+
+      if !docset || docset[:type] != :doc_comment
+        if inheritable
+          m[:inheritdoc] = {}
+        else
+          m[:private] = true
+        end
+        m[:autodetected] = true
+      end
+
+      if docset
+        docset[:code] = m
+        return false
+      else
+        # Get line number from third place at range array.
+        # This third item exists in forked EsprimaJS at
+        # https://github.com/nene/esprima/tree/linenr-in-range
+        m[:linenr] = pair["range"][2]
+        return true
+      end
+    end
+
+    # Looks up docset associated with given AST node.
+    # A dead-stupid and -slow implementation, but works.
+    def find_docset(ast)
+      @docs.find do |docset|
+        docset[:code] == ast
+      end
+    end
+
+    def make_method(name, ast=nil)
+      return {
+        :tagname => :method,
+        :name => name,
+        :params => make_params(ast)
+      }
+    end
+
+    def make_params(ast)
+      if ast && !empty_fn?(ast)
+        ast["params"].map {|p| {:name => to_s(p)} }
+      else
+        []
+      end
+    end
+
+    def make_property(name=nil, ast=nil, tagname=:property)
+      return {
+        :tagname => tagname,
+        :name => name,
+        :type => make_value_type(ast),
+        :default => make_default(ast),
+      }
+    end
+
+    def make_default(ast)
+      ast && to_value(ast) != nil ? to_s(ast) : nil
+    end
+
+    def make_value_type(ast)
+      if ast
+        v = to_value(ast)
+        if v.is_a?(String)
+          "String"
+        elsif v.is_a?(Numeric)
+          "Number"
+        elsif v.is_a?(TrueClass) || v.is_a?(FalseClass)
+          "Boolean"
+        elsif v.is_a?(Array)
+          "Array"
+        elsif v.is_a?(Hash)
+          "Object"
+        elsif v == :regexp
+          "RegExp"
+        else
+          nil
+        end
+      else
+        nil
+      end
+    end
+
+    # -- various helper methods --
+
+    # Iterates over keys and values in ObjectExpression.  The keys
+    # are turned into strings, but values are left as is for further
+    # processing.
+    def each_pair_in_object_expression(ast)
+      return unless ast && ast["type"] == "ObjectExpression"
+
+      ast["properties"].each do |p|
+        yield(key_value(p["key"]), p["value"], p)
+      end
+    end
+
+    # Converts object expression property key to string value
+    def key_value(key)
+      @evaluator.key_value(key)
+    end
+
+    # Fully serializes the node
+    def to_s(ast)
+      @serializer.to_s(ast)
+    end
+
+    # Converts AST node into a value.
+    def to_value(ast)
+      begin
+        @evaluator.to_value(ast)
+      rescue
+        nil
+      end
+    end
+  end
+
+end
+