jsduck 5.0.0.beta2 → 5.0.0.beta3

data/lib/jsduck/js/node.rb

@@ -80,6 +80,35 @@ module JsDuck
         end
       end
 
+      # Returns the type of node.
+      def type
+        @node["type"]
+      end
+
+      # Extracts all sub-statements and sub-expressions from AST node.
+      # Without looking at the type of node, we just take all the
+      # sub-hashes and -arrays.
+      #
+      # A downside of this simple algorithm is that the statements can
+      # end up in different order than they are in source code.  For
+      # example the IfStatement has three parts in the following
+      # order: "test", "consequent", "alternate": But because we're
+      # looping over a hash, they might end up in a totally different
+      # order.
+      def body
+        body = []
+        @node.each_pair do |key, value|
+          if key == "type" || key == "range"
+            # ignore
+          elsif value.is_a?(Array)
+            body.concat(value.map {|v| Js::Node.create(v) })
+          elsif value.is_a?(Hash)
+            body << Js::Node.create(value)
+          end
+        end
+        body
+      end
+
       # Iterates over keys and values in ObjectExpression.  The keys
       # are turned into strings, but values are left as is for further
       # processing.

data/lib/jsduck/js/property.rb

@@ -0,0 +1,64 @@
+require "jsduck/util/singleton"
+
+module JsDuck
+  module Js
+
+    # Auto-detection of properties.
+    class Property
+      include Util::Singleton
+
+      # Checks if AST node is a property, and if so, returns doc-hash
+      # with property name and various auto-detected attributes.
+      # When not a property returns nil.
+      def detect(ast)
+        exp = ast.expression_statement? ? ast["expression"] : nil
+        var = ast.variable_declaration? ? ast["declarations"][0] : nil
+
+        # foo = ...
+        if exp && exp.assignment_expression?
+          make(exp["left"].to_s, exp["right"])
+
+          # var foo = ...
+        elsif var
+          make(var["id"].to_s, var["init"])
+
+          # foo: ...
+        elsif ast.property?
+          make(ast["key"].key_value, ast["value"])
+
+          # foo;
+        elsif exp && exp.identifier?
+          make(exp.to_s)
+
+          # "foo"  (inside some expression)
+        elsif ast.string?
+          make(ast.to_value)
+
+          # "foo";  (as a statement of it's own)
+        elsif exp && exp.string?
+          make(exp.to_value)
+
+        else
+          nil
+        end
+      end
+
+      # Produces a doc-hash for a property.
+      def make(name=nil, ast=nil)
+        return {
+          :tagname => :property,
+          :name => name,
+          :type => ast && ast.value_type,
+          :default => ast && default(ast),
+        }
+      end
+
+      private
+
+      def default(ast)
+        ast.to_value != nil ? ast.to_s : nil
+      end
+
+    end
+  end
+end

data/lib/jsduck/js/{function.rb → returns.rb}

@@ -3,10 +3,15 @@ require "jsduck/util/singleton"
 module JsDuck
   module Js
 
-    # Analyzes the AST of a FunctionDeclaration or FunctionExpression.
-    class Function
+    # Analyzes the AST of a Function for possible return values.
+    class Returns
       include Util::Singleton
 
+      # True when function always finishes with returning this.
+      def chainable?(ast)
+        detect(ast) == [:this]
+      end
+
       # Detects possible return types of the given function.
       #
       # For now there are three possible detected return values:
@@ -18,7 +23,7 @@ module JsDuck
       #
       # * :other - some other value is returned.
       #
-      def return_types(ast)
+      def detect(ast)
         h = return_types_hash(ast["body"]["body"])
 
         # Replace the special :void value that signifies possibility of

data/lib/jsduck/js/scoped_traverser.rb

@@ -0,0 +1,42 @@
+module JsDuck
+  module Js
+
+    # Traverses syntax tree while keeping track of variables that are
+    # bound to `this`.
+    class ScopedTraverser
+      def initialize
+        @this_map = {
+          "this" => true
+        }
+      end
+
+      # Loops recursively over all the sub-nodes of the given node,
+      # calling the provided block for each sub-node.
+      def traverse(node, &block)
+        node.body.each do |child|
+          yield child
+
+          if this_var?(child)
+            var_name = child["id"].to_s
+            @this_map[var_name] = true
+          end
+
+          traverse(child, &block)
+        end
+      end
+
+      # True when variable with given name is bound to `this`.
+      def this?(var_name)
+        @this_map[var_name]
+      end
+
+      private
+
+      # True when initialization of variable with `this`
+      def this_var?(node)
+        node.type == "VariableDeclarator" && node["init"].type == "ThisExpression"
+      end
+
+    end
+  end
+end

data/lib/jsduck/logger.rb

@@ -10,8 +10,14 @@ module JsDuck
     # Set to true to enable verbose logging
     attr_accessor :verbose
 
+    # Set true to force colored output.
+    # Set false to force no colors.
+    attr_accessor :colors
+
     def initialize
       @verbose = false
+      @colors = nil
+
       @warning_docs = [
         [:global, "Member doesn't belong to any class"],
         [:inheritdoc, "@inheritdoc referring to unknown class or member"],
@@ -36,6 +42,7 @@ module JsDuck
         [:type_syntax, "Syntax error in {type definition}"],
         [:type_name, "Unknown type referenced in {type definition}"],
         [:enum, "Enum with invalid values or no values at all"],
+        [:fires, "@fires references unknown event"],
 
         [:image, "{@img} referring to missing file"],
         [:image_unused, "An image exists in --images dir that's not used"],
@@ -173,6 +180,11 @@ module JsDuck
       $stderr.puts error.backtrace
     end
 
+    # True when at least one warning was logged.
+    def warnings_logged?
+      @shown_warnings.length > 0
+    end
+
     private
 
     COLORS = {
@@ -193,7 +205,7 @@ module JsDuck
     # Only does color output when STDERR is attached to TTY
     # i.e. is not piped/redirected.
     def paint(color_name, msg)
-      if Util::OS.windows? || !$stderr.tty?
+      if @colors == false || @colors == nil && (Util::OS.windows? || !$stderr.tty?)
         msg
       else
         COLORS[color_name] + msg + CLEAR

data/lib/jsduck/merger.rb

@@ -14,15 +14,17 @@ module JsDuck
     # producing hash as a result.
     def merge(docset, filename="", linenr=0)
       docs = docset[:comment]
-      code = docset[:code]
+      code = process_code(docset[:tagname], docset[:code])
 
       h = {
         :tagname => docset[:tagname],
+        :name => docs[:name] || code[:name] || "",
+        :autodetected => code[:autodetected] || {},
         :files => [{:filename => filename, :linenr => linenr}],
       }
 
-      invoke_merge_in_tags(h, docs, code)
       general_merge(h, docs, code)
+      invoke_merge_in_member_tag(h, docs, code)
 
       # Needs to be calculated last, as it relies on the existance of
       # :name, :static and :tagname fields.
@@ -33,42 +35,47 @@ module JsDuck
 
     private
 
-    # Invokes the #merge methods of tags registered for the given
-    # merge context.
-    def invoke_merge_in_tags(h, docs, code)
-      TagRegistry.mergers(h[:tagname]).each do |tag|
-        tag.merge(h, docs, code)
-      end
+    # Applies processing to extract fields relevant to the member type.
+    def process_code(tagname, code)
+      TagRegistry.get_by_name(tagname).process_code(code)
+    end
+
+    # Invokes the #merge method in corresponding member or :class tag.
+    def invoke_merge_in_member_tag(h, docs, code)
+      TagRegistry.get_by_name(h[:tagname]).merge(h, docs, code)
     end
 
     # Applies default merge algorithm to the rest of the data.
     def general_merge(h, docs, code)
-      # Merge in all items in docs that don't occour already in result.
+      # Add all items in docs not already in result.
       docs.each_pair do |key, value|
-        h[key] = value unless h.has_key?(key) || Merger::explicit?(key)
+        h[key] = value unless h[key]
       end
-      # Then add all in the items from code not already in result.
-      code.each_pair do |key, value|
-        h[key] = value unless h.has_key?(key) || Merger::explicit?(key)
+
+      # Add all items in code not already in result and mark them as
+      # auto-detected.  But only if the explicit and auto-detected
+      # names don't conflict.
+      if Merger.can_be_autodetected?(docs, code)
+        code.each_pair do |key, value|
+          unless h[key]
+            h[key] = value
+            mark_autodetected(h, key)
+          end
+        end
       end
     end
 
-    # True when given key gets merged explicitly and should therefore
-    # be skipped when auto-merging.
-    def self.explicit?(key)
-      @explicit = explictly_merged_fields unless @explicit
-      @explicit[key]
+    # True if the name detected from code matches with explicitly
+    # documented name.  Also true when no explicit name documented.
+    #
+    # Note: This method is also called from ParamsMerger.
+    def self.can_be_autodetected?(docs, code)
+      docs[:name] == nil || docs[:name] == code[:name]
     end
 
-    # Generates a lookup-hash of tagnames which are explicitly merged.
-    def self.explictly_merged_fields
-      mergers = {}
-      member_types = TagRegistry.member_type_names + [:class]
-      tags = member_types.map {|type| TagRegistry.mergers(type) }.flatten.uniq
-      tags.each do |tag|
-        mergers[tag.tagname] = true
-      end
-      mergers
+    # Stores the key as flag into h[:autodetected]
+    def mark_autodetected(h, key)
+      h[:autodetected][key] = true
     end
 
   end

data/lib/jsduck/news.rb

@@ -0,0 +1,128 @@
+require 'jsduck/util/null_object'
+require 'jsduck/columns'
+
+module JsDuck
+
+  class News
+    # Creates News object from relations data when --import option
+    # specified.
+    def self.create(relations, doc_formatter, opts)
+      if opts[:imports].length > 0
+        News.new(relations, doc_formatter)
+      else
+        Util::NullObject.new(:to_html => "")
+      end
+    end
+
+    # Generates list of new classes & members in this version.
+    def initialize(relations, doc_formatter)
+      @doc_formatter = doc_formatter
+      @columns = Columns.new(:members)
+      @new_items = filter_new_items(relations)
+    end
+
+    # Returns the HTML
+    def to_html(style="")
+      return [
+        "<div id='news-content' style='#{style}'>",
+          "<div class='section'>",
+            "<h1>New in this version</h1>",
+            render_columns(@new_items),
+            "<div style='clear:both'></div>",
+          "</div>",
+        "</div>",
+      ].flatten.join("\n")
+    end
+
+    private
+
+    def filter_new_items(relations)
+      classes = []
+      new_items = []
+
+      relations.each do |cls|
+        if !cls[:private]
+          if cls[:new]
+            classes << cls
+          else
+            members = filter_new_members(cls)
+            if members.length > 0
+              new_items << {:name => cls[:name], :members => members}
+            end
+          end
+        end
+      end
+
+      new_items.sort! {|a, b| a[:name] <=> b[:name] }
+
+      # Place the new classes section at the beginning
+      if classes.length > 0
+        new_items.unshift({:name => "New classes", :members => classes})
+      end
+
+      new_items
+    end
+
+    def filter_new_members(cls)
+      members = []
+      cls.all_local_members.each do |m|
+        members << m if m[:new] && visible?(m)
+      end
+      members = discard_accessors(members)
+      members.sort! {|a, b| a[:name] <=> b[:name] }
+    end
+
+    def visible?(member)
+      !member[:private] && !member[:hide]
+    end
+
+    def discard_accessors(members)
+      accessors = {}
+      members.find_all {|m| m[:accessor] }.each do |cfg|
+        accessors["set" + upcase_first(cfg[:name])] = true
+        accessors["get" + upcase_first(cfg[:name])] = true
+        accessors[cfg[:name].downcase + "change"] = true if cfg[:evented]
+      end
+
+      members.reject {|m| accessors[m[:name]] }
+    end
+
+    def upcase_first(str)
+      str[0,1].upcase + str[1..-1]
+    end
+
+    def render_columns(new_items)
+      align = ["left-column", "middle-column", "right-column"]
+      i = -1
+      return @columns.split(new_items, 3).map do |col|
+        i += 1
+        [
+          "<div class='#{align[i]}'>",
+          render_col(col),
+          "</div>",
+        ]
+      end
+    end
+
+    def render_col(col)
+      return col.map do |item|
+        [
+          "<h3>#{item[:name]}</h3>",
+          "<ul class='links'>",
+          item[:members].map {|m| "<li>" + link(m) + "</li>" },
+          "</ul>",
+        ]
+      end
+    end
+
+    def link(m)
+      if m[:tagname] == :class
+        @doc_formatter.link(m[:name], nil, m[:name])
+      else
+        @doc_formatter.link(m[:owner], m[:name], m[:name], m[:tagname], m[:static])
+      end
+    end
+
+  end
+
+end

data/lib/jsduck/options.rb

@@ -42,9 +42,11 @@ module JsDuck
     attr_accessor :tests
     attr_accessor :comments_url
     attr_accessor :comments_domain
+    attr_accessor :search
     attr_accessor :ignore_html
 
     # Debugging
+    attr_accessor :warnings_exit_nonzero
     attr_accessor :template_dir
     attr_accessor :template_links
     attr_accessor :extjs_path
@@ -92,8 +94,7 @@ module JsDuck
       ]
       @ext4_events = nil
 
-      @version = "5.0.0.beta2"
-
+      @version = "5.0.0.beta3"
       # Customizing output
       @title = "Documentation - JSDuck"
       @header = "<strong>Documentation</strong> JSDuck"
@@ -121,9 +122,11 @@ module JsDuck
       @tests = false
       @comments_url = nil
       @comments_domain = nil
+      @search = {}
       @ignore_html = {}
 
       # Debugging
+      @warnings_exit_nonzero = false
       @root_dir = File.dirname(File.dirname(File.dirname(__FILE__)))
       @template_dir = @root_dir + "/template-min"
       @template_links = false
@@ -140,6 +143,7 @@ module JsDuck
       Logger.set_warning(:all, true)
       Logger.set_warning(:link_auto, false)
       Logger.set_warning(:param_count, false)
+      Logger.set_warning(:fires, false)
 
       @optparser = create_option_parser
     end
@@ -450,6 +454,8 @@ module JsDuck
         end
 
         opts.on('--comments-domain=STRING',
+          "A name identifying the subset of comments.",
+          "",
           "A string consisting of <name>/<version>.",
           "",
           "For example: ext-js/4",
@@ -458,6 +464,37 @@ module JsDuck
           @comments_domain = domain
         end
 
+        opts.on('--search-url=URL',
+          "Address of guides search server.",
+          "",
+          "When supplied, the search for guides is performed through this",
+          "external service and the results merged together with API search.",
+          "The search server must respond to JSONP requests.",
+          "",
+          "For example: http://sencha.com/docsearch",
+          "",
+          "Must be used together with --search-domain option.",
+          "",
+          "This option is EXPERIMENTAL.") do |url|
+          @search[:url] = url
+        end
+
+        opts.on('--search-domain=STRING',
+          "A name identifying the subset to search from.",
+          "",
+          "A string consisting of <name>/<version>.",
+          "",
+          "Tells the search engine which product and version",
+          "to include into search.",
+          "",
+          "For example: Ext JS/4.2.0",
+          "",
+          "Must be used together with --search-url option.",
+          "",
+          "This option is EXPERIMENTAL.") do |domain|
+          @search[:product], @search[:version] = domain.split(/\//)
+        end
+
         opts.separator ""
         opts.separator "Tweaking:"
         opts.separator ""
@@ -653,6 +690,26 @@ module JsDuck
           end
         end
 
+        opts.on('--warnings-exit-nonzero',
+          "Exits with non-zero exit code on warnings.",
+          "",
+          "By default JSDuck only exits with non-zero exit code",
+          "when a fatal error is encountered (code 1).",
+          "",
+          "With this option the exit code will be 2 when any warning",
+          "gets printed.") do
+          @warnings_exit_nonzero = true
+        end
+
+        opts.on('--[no-]color',
+          "Turn on/off colorized terminal output.",
+          "",
+          "By default the colored output is on, but gets disabled",
+          "automatically when output is not an interactive terminal",
+          "(or when running on Windows system).") do |on|
+          Logger.colors = on
+        end
+
         opts.on('-p', '--processes=COUNT',
           "The number of parallel processes to use.",
           "",