jsduck 5.0.0.beta2 → 5.0.0.beta3

data/lib/jsduck/params_merger.rb

@@ -0,0 +1,47 @@
+require "jsduck/logger"
+require "jsduck/merger"
+
+module JsDuck
+  # Performs the merging of :params field.
+  # Used by Method, Event and CssMixin members.
+  class ParamsMerger
+    # Ensures the existance of params array.
+    # Defaults type of each parameter to "Object".
+    # Logs warnings for inconsistencies between params in code and in docs.
+    def self.merge(h, docs, code)
+      h[:params] = [] unless h[:params]
+
+      h[:params].each do |p|
+        p[:type] = "Object" unless p[:type]
+      end
+
+      check_consistency(docs, code, h[:files].first)
+    end
+
+    def self.check_consistency(docs, code, file)
+      explicit = docs[:params] || []
+      implicit = JsDuck::Merger.can_be_autodetected?(docs, code) ? (code[:params] || []) : []
+      ex_len = explicit.length
+      im_len = implicit.length
+
+      if ex_len == 0 || im_len == 0
+        # Skip when either no implicit or explicit params
+      elsif ex_len != im_len && explicit.last[:type] =~ /\.\.\.$/
+        # Skip when vararg params are in play.
+      elsif ex_len < im_len
+        # Warn when less parameters documented than found from code.
+        JsDuck::Logger.warn(:param_count, "Detected #{im_len} params, but only #{ex_len} documented.", file)
+      elsif ex_len > im_len
+        # Warn when more parameters documented than found from code.
+        JsDuck::Logger.warn(:param_count, "Detected #{im_len} params, but #{ex_len} documented.", file)
+      elsif implicit.map {|p| p[:name] } != explicit.map {|p| p[:name] }
+        # Warn when parameter names don't match up.
+        ex_names = explicit.map {|p| p[:name] }
+        im_names = implicit.map {|p| p[:name] }
+        str = ex_names.zip(im_names).map {|p| ex, im = p; ex == im ? ex : (ex||"")+"/"+(im||"") }.join(", ")
+        JsDuck::Logger.warn(:param_count, "Documented and auto-detected params don't match: #{str}", file)
+      end
+    end
+
+  end
+end

data/lib/jsduck/process/accessors.rb

@@ -127,9 +127,15 @@ module JsDuck
       end
 
       # Copy over from @cfg all the fields that aren't already present.
-      # Except :type and :default which don't make sense for methods and events.
       def add_shared(hash, cfg)
-        ignored_fields = [:type, :default, :accessor, :evented]
+        ignored_fields = [
+          # These don't make sense for methods and events.
+          :type, :default,
+          # It's the config that's tagged with these, don't propagate them to methods/events.
+          :accessor, :evented,
+          # The :doc field get auto-created and we don't want any other docs.
+          :inheritdoc, :localdoc,
+        ]
 
         cfg.each_pair do |key, value|
           hash[key] = value unless ignored_fields.include?(key) || hash[key]

data/lib/jsduck/process/fires.rb

@@ -0,0 +1,71 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Process
+
+    # Expands lists of fired events to take into account events fired
+    # by all the methods that get called by a method.
+    class Fires
+      def initialize(relations)
+        @relations = relations
+        # Map of methods for which all @fires tags have been detected.
+        # So we don't repeat the resolving.
+        @detected = {}
+        # Map of methods that we're currently resolving.
+        # So we don't recurse into infinity.
+        @call_chain = {}
+      end
+
+      # Populates @fires tags with additional events.
+      def process_all!
+        @relations.each do |cls|
+          cls.find_members(:tagname => :method, :static => false).each do |m|
+            @call_chain = {m[:name] => true}
+            detect_fires(cls, m)
+          end
+        end
+      end
+
+      private
+
+      def detect_fires(cls, m)
+        if m[:autodetected][:fires] && m[:method_calls] && !detected?(m)
+          m[:fires] = events_from_methods(cls, m[:method_calls]).concat(m[:fires] || []).sort.uniq
+          mark_detected(m)
+        end
+
+        m[:fires]
+      end
+
+      def mark_detected(m)
+        @detected[m[:owner]] = {} unless @detected[m[:owner]]
+        @detected[m[:owner]][m[:name]] = true
+      end
+
+      def detected?(m)
+        cls = @detected[m[:owner]]
+        cls && cls[m[:name]]
+      end
+
+      def events_from_methods(cls, methods)
+        events = []
+
+        methods.each do |name|
+          if !@call_chain[name]
+            @call_chain[name] = true
+            m = cls.find_members(:tagname => :method, :name => name, :static => false)[0]
+            if m
+              fires = detect_fires(cls, m)
+              events.concat(fires) if fires
+            end
+            @call_chain[name] = false
+          end
+        end
+
+        events.sort.uniq
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/process/importer.rb

@@ -28,9 +28,11 @@ module JsDuck
 
       # Reads in data from all .json files in directory
       def read(ver)
+        ensure_correct_format(ver[:path])
+
         # Map list of files into pairs of (classname, members-hash)
         pairs = Util::Parallel.map(Dir[ver[:path] + "/*.json"]) do |filename|
-          JsDuck::Logger.log("Importing #{ver[:version]}", filename)
+          Logger.log("Importing #{ver[:version]}", filename)
           json = Util::Json.read(filename)
           [json["name"],  members_id_index(json)]
         end
@@ -39,6 +41,22 @@ module JsDuck
         return Hash[ pairs ]
       end
 
+      def ensure_correct_format(path)
+        # Read first JSON file in import dir
+        json = Util::Json.read(Dir[path + "/*.json"].first)
+
+        unless correct_format?(json)
+          Logger.fatal("Bad format for importing: #{path}")
+          Logger.fatal("Export format changed in 5.0.0 beta 2.")
+          Logger.fatal("Maybe you forgot to re-generate the exports with new JSDuck.")
+          exit(1)
+        end
+      end
+
+      def correct_format?(json)
+        json["members"].is_a?(Array)
+      end
+
       # creates index of all class members
       def members_id_index(json)
         index = {}

data/lib/jsduck/render/class.rb

@@ -1,6 +1,6 @@
-require 'jsduck/render/signature'
 require 'jsduck/render/tags'
 require 'jsduck/render/sidebar'
+require 'jsduck/tag_registry'
 
 module JsDuck
   module Render
@@ -13,7 +13,6 @@ module JsDuck
 
       def render(cls)
         @cls = cls
-        @signature = Render::Signature.new(cls)
 
         return [
           "<div>",
@@ -122,8 +121,8 @@ module JsDuck
                 "<br/>",
                 @opts.source ? "<a href='source/#{m[:files][0][:href]}' target='_blank' class='view-source'>view source</a>" : "",
               "</div>",
-              # method params signature or property type signature
-              @signature.render(m),
+              render_member_signature(m),
+              render_tag_signature(m),
             "</div>",
             # short and long descriptions
             "<div class='description'>",
@@ -138,6 +137,14 @@ module JsDuck
         ]
       end
 
+      def render_member_signature(m)
+        TagRegistry.get_by_name(m[:tagname]).to_html(m, @cls)
+      end
+
+      def render_tag_signature(m)
+        Render::Tags.render_signature(m)
+      end
+
     end
 
   end

data/lib/jsduck/render/signature_util.rb

@@ -0,0 +1,14 @@
+module JsDuck
+  module Render
+
+    # Helper method for rendering the link in method/property signature
+    class SignatureUtil
+
+      def self.link(class_name, member_id, text)
+        "<a href='#!/api/#{class_name}-#{member_id}' class='name expandable'>#{text}</a>"
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/tag/alias.rb

@@ -9,7 +9,6 @@ module JsDuck::Tag
       @repeatable = true
       @ext_define_pattern = "alias"
       @ext_define_default = {:aliases => []}
-      @merge_context = :class
     end
 
     # For backwards compatibility decide whether the @alias was used
@@ -39,24 +38,5 @@ module JsDuck::Tag
       cls[:aliases] += JsDuck::Js::Utils.make_string_list(ast)
     end
 
-    def merge(h, docs, code)
-      h[:aliases] = build_aliases_hash(docs[:aliases] || code[:aliases] || [])
-    end
-
-    # Given array of full alias names like "foo.bar", "foo.baz"
-    # build hash like {"foo" => ["bar", "baz"]}
-    def build_aliases_hash(aliases)
-      hash={}
-      aliases.each do |a|
-        if a =~ /^([^.]+)\.(.+)$/
-          if hash[$1]
-            hash[$1] << $2
-          else
-            hash[$1] = [$2]
-          end
-        end
-      end
-      hash
-    end
   end
 end

data/lib/jsduck/tag/alternate_class_names.rb

@@ -8,11 +8,6 @@ module JsDuck::Tag
       @repeatable = true
       @ext_define_pattern = "alternateClassName"
       @ext_define_default = {:alternateClassNames => []}
-      @merge_context = :class
-    end
-
-    def merge(h, docs, code)
-      h[@tagname] = docs[@tagname] || code[@tagname] || []
     end
   end
 end

data/lib/jsduck/tag/cfg.rb

@@ -1,18 +1,17 @@
-require "jsduck/tag/tag"
+require "jsduck/tag/member_tag"
 require "jsduck/doc/subproperties"
 
 module JsDuck::Tag
-  class Cfg < Tag
+  class Cfg < MemberTag
     def initialize
       @pattern = "cfg"
       @tagname = :cfg
       @repeatable = true
       @member_type = {
-        :name => :cfg,
-        :category => :property_like,
         :title => "Config options",
         :toolbar_title => "Configs",
         :position => MEMBER_POS_CFG,
+        :icon => File.dirname(__FILE__) + "/icons/cfg.png",
         :subsections => [
           {:title => "Required config options", :filter => {:required => true}},
           {:title => "Optional config options", :filter => {:required => false}, :default => true},
@@ -22,7 +21,13 @@ module JsDuck::Tag
 
     # @cfg {Type} [name=default] (required) ...
     def parse_doc(p, pos)
-      tag = p.standard_tag({:tagname => :cfg, :type => true, :name => true})
+      tag = p.standard_tag({
+          :tagname => :cfg,
+          :type => true,
+          :name => true,
+          :default => true,
+          :optional => true
+        })
       tag[:optional] = false if parse_required(p)
       tag[:doc] = :multiline
       tag
@@ -45,5 +50,25 @@ module JsDuck::Tag
       h[:properties] = nested[:properties]
       h[:name] = nested[:name]
     end
+
+    def process_code(code)
+      h = super(code)
+      h[:type] = code[:type]
+      h[:default] = code[:default]
+      h[:accessor] = code[:accessor]
+      h[:evented] = code[:evented]
+      h
+    end
+
+    # Do the merging of :type field
+    def merge(h, docs, code)
+      if h[:type] == nil
+        h[:type] = code[:tagname] == :method ? "Function" : "Object"
+      end
+    end
+
+    def to_html(cfg, cls)
+      member_link(cfg) + " : " + cfg[:html_type]
+    end
   end
 end

data/lib/jsduck/tag/class.rb

@@ -5,7 +5,6 @@ module JsDuck::Tag
     def initialize
       @pattern = "class"
       @tagname = :class
-      @merge_context = :class
     end
 
     # @class name
@@ -20,9 +19,53 @@ module JsDuck::Tag
       h[:name] = tags[0][:name]
     end
 
-    # Ensure the empty members array.
+    # Although class is not a member, it also has the auto-detected
+    # part from code. So this method gets called by Merger.
+    #
+    # If we did detect code as a class use all the auto-detected
+    # fields, otherwise use only the name field.
+    def process_code(code)
+      if code[:tagname] == :class
+        code
+      else
+        {:name => code[:name] }
+      end
+    end
+
     def merge(h, docs, code)
+      # Ensure the empty members array.
       h[:members] = []
+      # Ignore extending of the Object class
+      h[:extends] = nil if h[:extends] == "Object"
+      # Default alternateClassNames list to empty array
+      h[:alternateClassNames] = [] unless h[:alternateClassNames]
+      # Turn :aliases field into hash
+      h[:aliases] = build_aliases_hash(h[:aliases] || [])
+
+      # Takes the :enum always from docs, but the :doc_only can come
+      # from either code or docs.
+      if docs[:enum]
+        h[:enum] = docs[:enum]
+        h[:enum][:doc_only] = docs[:enum][:doc_only] || (code[:enum] && code[:enum][:doc_only])
+      end
+    end
+
+    private
+
+    # Given array of full alias names like "foo.bar", "foo.baz"
+    # build hash like {"foo" => ["bar", "baz"]}
+    def build_aliases_hash(aliases)
+      hash={}
+      aliases.each do |a|
+        if a =~ /^([^.]+)\.(.+)$/
+          if hash[$1]
+            hash[$1] << $2
+          else
+            hash[$1] = [$2]
+          end
+        end
+      end
+      hash
     end
   end
 end

data/lib/jsduck/tag/css_mixin.rb

@@ -1,17 +1,21 @@
-require "jsduck/tag/tag"
+require "jsduck/tag/member_tag"
 
 module JsDuck::Tag
   # As of now there is no @css_mixin tag available in CSS files.  This
   # class just exists to define that we have a member type called
   # :css_mixin.
-  class CssMixin < Tag
+  class CssMixin < MemberTag
     def initialize
+      @tagname = :css_mixin
       @member_type = {
-        :name => :css_mixin,
-        :category => :method_like,
         :title => "CSS Mixins",
         :position => MEMBER_POS_CSS_MIXIN,
+        :icon => File.dirname(__FILE__) + "/icons/css_mixin.png"
       }
     end
+
+    def to_html(mixin, cls)
+      member_link(mixin) + member_params(mixin[:params])
+    end
   end
 end

data/lib/jsduck/tag/css_var.rb

@@ -1,22 +1,27 @@
-require "jsduck/tag/tag"
+require "jsduck/tag/member_tag"
 
 module JsDuck::Tag
-  class CssVar < Tag
+  class CssVar < MemberTag
     def initialize
       @pattern = "var"
       @tagname = :css_var
       @member_type = {
-        :name => :css_var,
-        :category => :property_like,
         :title => "CSS Variables",
         :toolbar_title => "CSS Vars",
         :position => MEMBER_POS_CSS_VAR,
+        :icon => File.dirname(__FILE__) + "/icons/css_var.png"
       }
     end
 
     # @var {Type} [name=default] ...
     def parse_doc(p, pos)
-      p.standard_tag({:tagname => :css_var, :type => true, :name => true})
+      p.standard_tag({
+          :tagname => :css_var,
+          :type => true,
+          :name => true,
+          :default => true,
+          :optional => true
+        })
     end
 
     def process_doc(h, tags, pos)
@@ -25,5 +30,21 @@ module JsDuck::Tag
       h[:type] = p[:type]
       h[:default] = p[:default]
     end
+
+    def process_code(code)
+      h = super(code)
+      h[:type] = code[:type]
+      h[:default] = code[:default]
+      h
+    end
+
+    # Set default value for :type field
+    def merge(h, docs, code)
+      h[:type] = "Object" unless h[:type]
+    end
+
+    def to_html(var, cls)
+      member_link(var) + " : " + var[:html_type]
+    end
   end
 end