jsduck 4.0.1 → 4.1.1

data/lib/jsduck/enum.rb

@@ -25,8 +25,8 @@ module JsDuck
 
     # Given an enum class, returns the type infered from its values.
     def infer_type(cls)
-      if cls[:members][:property].length > 0
-        types = cls[:members][:property].map {|p| p[:type] }
+      if cls[:members].length > 0
+        types = cls[:members].map {|p| p[:type] }
         types.sort.uniq.join("/")
       else
         "Object"
@@ -37,7 +37,7 @@ module JsDuck
     def expand_default(cls)
       if cls[:enum][:default] =~ /\A(.*)\.\*\Z/
         each_alias($1) do |name, owner|
-          cls[:members][:property] << {
+          cls[:members] << {
             :tagname => :property,
             :id => 'property-' + name,
             :name => name,
@@ -64,7 +64,7 @@ module JsDuck
     # Remove the auto-inserted inheritdoc tag so the auto-detected enum
     # values default to being public.
     def strip_inheritdoc(cls)
-      cls[:members][:property].each do |p|
+      cls[:members].each do |p|
         p[:inheritdoc] = nil if p[:autodetected]
       end
     end

data/lib/jsduck/esprima.rb

@@ -1,6 +1,6 @@
 require 'v8'
-require 'json'
-require 'singleton'
+require 'jsduck/util/json'
+require 'jsduck/util/singleton'
 
 module JsDuck
 
@@ -9,12 +9,18 @@ module JsDuck
   # Initialized as singleton to avoid loading the esprima.js more
   # than once - otherwise performace will severely suffer.
   class Esprima
-    include Singleton
+    include Util::Singleton
 
     def initialize
       @v8 = V8::Context.new
       esprima = File.dirname(File.dirname(File.dirname(File.expand_path(__FILE__))))+"/esprima/esprima.js";
+
+      # Esprima attempts to assign to window.esprima, but our v8
+      # engine has no global window variable defined.  So define our
+      # own and then grab esprima out from it again.
+      @v8.eval("var window = {};")
       @v8.load(esprima)
+      @v8.eval("var esprima = window.esprima;")
     end
 
     # Parses JavaScript source code using Esprima.js
@@ -23,7 +29,7 @@ module JsDuck
     def parse(input)
       @v8['js'] = input
       json = @v8.eval("JSON.stringify(esprima.parse(js, {comment: true, range: true, raw: true}))")
-      return JSON.parse(json, :max_nesting => false)
+      return Util::Json.parse(json, :max_nesting => false)
     end
 
   end

data/lib/jsduck/examples.rb

@@ -1,5 +1,5 @@
-require 'jsduck/json_duck'
-require 'jsduck/null_object'
+require 'jsduck/util/json'
+require 'jsduck/util/null_object'
 require 'jsduck/grouped_asset'
 
 module JsDuck
@@ -11,16 +11,16 @@ module JsDuck
       if filename
         Examples.new(filename, opts)
       else
-        NullObject.new(:to_array => [], :[] => nil)
+        Util::NullObject.new(:to_array => [], :[] => nil)
       end
     end
 
     # Parses examples config file
     def initialize(filename, opts)
-      @groups = JsonDuck.read(filename)
+      @groups = Util::Json.read(filename)
       @opts = opts
       fix_examples_data
-      build_map_by_name("Two examples have the same name", filename)
+      build_map_by_name
     end
 
     # Prefix all relative URL-s in examples list with path given in --examples-base-url

data/lib/jsduck/export_writer.rb

@@ -0,0 +1,62 @@
+require 'jsduck/util/stdout'
+require 'jsduck/exporter/full'
+require 'jsduck/exporter/examples'
+require 'jsduck/batch_formatter'
+require 'jsduck/class_writer'
+require 'jsduck/guide_writer'
+require 'fileutils'
+
+module JsDuck
+
+  # Performs the export in one of the export formats.
+  class ExportWriter
+    def initialize(relations, assets, opts)
+      @relations = relations
+      @assets = assets
+      @opts = opts
+    end
+
+    def write
+      format_classes
+
+      clean_output_dir unless @opts.output_dir == :stdout
+
+      export_classes
+      export_examples_in_guides if @opts.export == :examples
+
+      Util::Stdout.flush if @opts.output_dir == :stdout
+    end
+
+    private
+
+    def export_classes
+      cw = ClassWriter.new(get_exporter, @relations, @opts)
+      cw.write(@opts.output_dir, ".json")
+    end
+
+    def get_exporter
+      exporters = {
+        :full => Exporter::Full,
+        :examples => Exporter::Examples,
+      }
+      exporters[@opts.export]
+    end
+
+    def export_examples_in_guides
+      gw = GuideWriter.new(Exporter::Examples, @assets.guides, @opts)
+      gw.write(@opts.output_dir, ".json")
+    end
+
+    # -- util routines --
+
+    def clean_output_dir
+      FileUtils.rm_rf(@opts.output_dir)
+    end
+
+    def format_classes
+      BatchFormatter.format_all!(@relations, @assets, @opts)
+    end
+
+  end
+
+end

data/lib/jsduck/exporter/app.rb

@@ -0,0 +1,62 @@
+require 'jsduck/renderer'
+require 'jsduck/doc_formatter'
+require 'jsduck/exporter/full'
+
+module JsDuck
+  module Exporter
+
+    # Exports data for Docs app.
+    class App < Full
+      def initialize(relations, opts)
+        super(relations, opts)
+        @renderer = Renderer.new(opts)
+      end
+
+      # Returns compacted class data hash which contains an additional
+      # :html field with full HTML to show on class overview page.
+      def export(cls)
+        data = super(cls)
+        data[:html] = @renderer.render(data)
+        return compact(data)
+      end
+
+      private
+
+      # removes extra data from export
+      def compact(cls)
+        cls.delete(:doc)
+        cls[:members] = compact_members_group(cls[:members])
+        cls[:statics] = compact_members_group(cls[:statics])
+        cls[:files] = compact_files(cls[:files])
+        cls
+      end
+
+      def compact_members_group(group)
+        c_group = {}
+        group.each_pair do |type, members|
+          c_group[type] = members.map {|m| compact_member(m) }
+        end
+        c_group
+      end
+
+      def compact_member(m)
+        m_copy = {}
+        [:name, :tagname, :owner, :meta, :id].each do |key|
+          m_copy[key] = m[key]
+        end
+        m_copy
+      end
+
+      # Remove full path from filename for privacy considerations as the
+      # path can reveal information about the system where JSDuck was
+      # run.  The docs app doesn't need to have this information.
+      def compact_files(files)
+        files.map do |f|
+          {:filename => File.basename(f[:filename]), :href => f[:href]}
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/exporter/examples.rb

@@ -0,0 +1,58 @@
+require 'jsduck/inline_examples'
+
+module JsDuck
+  module Exporter
+
+    # Exporter for inline examples.
+    #
+    # It produces the following structure:
+    #
+    # {
+    #   :type => :class,  # can also be :guide
+    #   :name => "Panel",
+    #   :examples => [
+    #     {:code => "bla bla", :options => {}},
+    #     {:code => "bla bla", :options => {"raw" => true}},
+    #     ...
+    #   ]
+    # }
+    #
+    class Examples
+      def initialize(relations, opts)
+        # All params ignored, they're present to be compatible with
+        # other exporters.
+        @inline_examples = InlineExamples.new
+      end
+
+      # Returns hash of class name and inline examples
+      def export(cls)
+        examples = @inline_examples.extract(cls[:doc])
+        if examples.length > 0
+          {
+            :type => :class,
+            :name => cls[:name],
+            :examples => examples,
+          }
+        else
+          nil
+        end
+      end
+
+      # Returns hash of guide name and inline examples
+      def export_guide(guide)
+        examples = @inline_examples.extract(guide[:html] || "")
+        if examples.length > 0
+          {
+            :type => :guide,
+            :name => guide["name"],
+            :examples => examples,
+          }
+        else
+          nil
+        end
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/exporter/full.rb

@@ -0,0 +1,60 @@
+require 'jsduck/class'
+
+module JsDuck
+  module Exporter
+
+    # Exporter for all the class docs.
+    class Full
+      def initialize(relations, opts={})
+        @relations = relations
+        # opts parameter is here just for compatibility with other exporters
+      end
+
+      # Returns all data in Class object as hash.
+      def export(cls)
+        # Make copy of the internal data structure of a class
+        # so our modifications on it will be safe.
+        h = cls.internal_doc.clone
+
+        h[:members] = {}
+        h[:statics] = {}
+        Class.each_member_type do |tagname|
+          h[:members][tagname] = export_members(cls, {:tagname => tagname, :static => false})
+          h[:statics][tagname] = export_members(cls, {:tagname => tagname, :static => true})
+        end
+        h[:component] = cls.inherits_from?("Ext.Component")
+        h[:superclasses] = cls.superclasses.collect {|c| c[:name] }
+        h[:subclasses] = @relations.subclasses(cls).collect {|c| c[:name] }
+        h[:mixedInto] = @relations.mixed_into(cls).collect {|c| c[:name] }
+
+        h[:mixins] = cls.deps(:mixins).collect {|c| c[:name] }
+        h[:parentMixins] = cls.parent_deps(:mixins).collect {|c| c[:name] }
+        h[:requires] = cls.deps(:requires).collect {|c| c[:name] }
+        h[:uses] = cls.deps(:uses).collect {|c| c[:name] }
+
+        h
+      end
+
+      private
+
+      # Looks up members, and sorts them so that constructor method is first
+      def export_members(cls, cfg)
+        ms = cls.find_members(cfg)
+        ms.sort! {|a,b| a[:name] <=> b[:name] }
+        cfg[:tagname] == :method ? constructor_first(ms) : ms
+      end
+
+      # If methods list contains constructor, move it into the beginning.
+      def constructor_first(ms)
+        constr = ms.find {|m| m[:name] == "constructor" }
+        if constr
+          ms.delete(constr)
+          ms.unshift(constr)
+        end
+        ms
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/file_categories.rb

@@ -1,3 +1,6 @@
+require 'jsduck/logger'
+require 'jsduck/util/json'
+
 module JsDuck
 
   # Reads categories info from config file
@@ -9,11 +12,11 @@ module JsDuck
 
     # Parses categories in JSON file
     def generate
-      @categories = JsonDuck.read(@filename)
+      @categories = Util::Json.read(@filename)
 
       # Don't crash if old syntax is used.
       if @categories.is_a?(Hash) && @categories["categories"]
-        Logger.instance.warn(nil, 'Update categories file to contain just the array inside {"categories": [...]}', @filename)
+        Logger.warn(nil, 'Update categories file to contain just the array inside {"categories": [...]}', @filename)
         @categories = @categories["categories"]
       end
 
@@ -36,7 +39,7 @@ module JsDuck
       re = Regexp.new("^" + name.split(/\*/, -1).map {|part| Regexp.escape(part) }.join('.*') + "$")
       classes = @relations.to_a.find_all {|cls| re =~ cls[:name] && !cls[:private] }.map {|cls| cls[:name] }.sort
       if classes.length == 0
-        Logger.instance.warn(:cat_no_match, "No class found matching a pattern '#{name} in categories file'", @filename)
+        Logger.warn(:cat_no_match, "No class found matching a pattern '#{name} in categories file'", @filename)
       end
       classes
     end
@@ -56,7 +59,7 @@ module JsDuck
       # Check that each existing non-private class is listed
       @relations.each do |cls|
         unless listed_classes[cls[:name]] || cls[:private]
-          Logger.instance.warn(:cat_class_missing, "Class '#{cls[:name]}' not found in categories file", @filename)
+          Logger.warn(:cat_class_missing, "Class '#{cls[:name]}' not found in categories file", @filename)
         end
       end
     end

data/lib/jsduck/function_ast.rb

@@ -0,0 +1,99 @@
+require "jsduck/util/singleton"
+require "jsduck/serializer"
+require "jsduck/evaluator"
+
+module JsDuck
+
+  # Analyzes the AST of a FunctionDeclaration or FunctionExpression.
+  class FunctionAst
+    include Util::Singleton
+
+    # True when function always finishes by returning this.  False
+    # doesn't neccessarily mean that the function doesn't return this
+    # - rather it means our static analyzes wasn't able to determine
+    # what the function returns.
+    def chainable?(ast)
+      if ast && function?(ast)
+        body_returns(ast["body"]["body"])
+      else
+        false
+      end
+    end
+
+    private
+
+    def function?(ast)
+      ast["type"] == "FunctionDeclaration" || ast["type"] == "FunctionExpression"
+    end
+
+    def body_returns(body)
+      body = skip_returnless_statements(body)
+
+      return body.length > 0 && return_this?(body[0])
+    end
+
+    def return_this?(ast)
+      return?(ast) && !!ast["argument"] && this?(ast["argument"])
+    end
+
+    def return?(ast)
+      ast["type"] == "ReturnStatement"
+    end
+
+    def this?(ast)
+      ast["type"] == "ThisExpression"
+    end
+
+    def skip_returnless_statements(statements)
+      i = statements.find_index {|s| contains_return?(s) }
+      if i
+        statements.slice(i, statements.length)
+      else
+        []
+      end
+    end
+
+    def contains_return?(ast)
+      if return?(ast)
+        true
+      elsif control_flow?(ast)
+        extract_body(ast).any? {|s| contains_return?(s) }
+      else
+        false
+      end
+    end
+
+    def control_flow?(ast)
+      CONTROL_FLOW[ast["type"]]
+    end
+
+    def extract_body(ast)
+      body = []
+      CONTROL_FLOW[ast["type"]].each do |name|
+        statements = ast[name]
+        if statements.is_a?(Hash)
+          body << statements
+        else
+          body += Array(statements)
+        end
+      end
+      body
+    end
+
+    CONTROL_FLOW = {
+      "IfStatement" => ["consequent", "alternate"],
+      "SwitchStatement" => ["cases"],
+      "SwitchCase" => ["consequent"],
+      "ForStatement" => ["body"],
+      "ForInStatement" => ["body"],
+      "WhileStatement" => ["body"],
+      "DoWhileStatement" => ["body"],
+      "TryStatement" => ["block", "handlers", "finalizer"],
+      "CatchClause" => ["body"],
+      "WithStatement" => ["body"],
+      "LabeledStatement" => ["body"],
+      "BlockStatement" => ["body"],
+    }
+  end
+
+end