jsduck 5.0.0.beta2 → 5.0.0.beta3

data/lib/jsduck/tag/default.rb

@@ -1,5 +1,4 @@
 require "jsduck/tag/tag"
-require "jsduck/docs_code_comparer"
 require "jsduck/util/html"
 
 module JsDuck::Tag
@@ -9,19 +8,14 @@ module JsDuck::Tag
   #
   #     @cfg [blah=somedefault]
   #
-  # This tag class exists to take care of the merging of :default
-  # fields and to generate the "Defaults to:" text in final HTML.
+  # This tag class exists to generate the "Defaults to:" text in final
+  # HTML.
   class Default < Tag
     def initialize
       @tagname = :default
-      @merge_context = :property_like
       @html_position = POS_DEFAULT
     end
 
-    def merge(h, docs, code)
-      JsDuck::DocsCodeComparer.merge_if_matches(h, :default, docs, code)
-    end
-
     def to_html(m)
       return if m[:default] == "undefined"
 

data/lib/jsduck/tag/enum.rb

@@ -5,7 +5,6 @@ module JsDuck::Tag
     def initialize
       @pattern = "enum"
       @tagname = :enum
-      @merge_context = :class
       @html_position = POS_ENUM
       # Green box
       @css = <<-EOCSS
@@ -19,7 +18,13 @@ module JsDuck::Tag
 
     # @enum {Type} [name=default] ...
     def parse_doc(p, pos)
-      enum = p.standard_tag({:tagname => :enum, :type => true, :name => true})
+      enum = p.standard_tag({
+          :tagname => :enum,
+          :type => true,
+          :name => true,
+          :default => true,
+          :optional => true
+        })
 
       # @enum is a special case of class, so we also generate a class
       # tag with the same name as given for @enum.
@@ -36,14 +41,6 @@ module JsDuck::Tag
       }
     end
 
-    # Takes the :enum always from docs, but the :doc_only can come
-    # from either code or docs.
-    def merge(h, docs, code)
-      return unless docs[:enum]
-      h[:enum] = docs[:enum]
-      h[:enum][:doc_only] = docs[:enum][:doc_only] || (code[:enum] && code[:enum][:doc_only])
-    end
-
     def to_html(cls)
       if cls[:enum][:doc_only]
         first = cls[:members][0] || {:name => 'foo', :default => '"foo"'}

data/lib/jsduck/tag/event.rb

@@ -1,15 +1,15 @@
-require "jsduck/tag/tag"
+require "jsduck/tag/member_tag"
+require "jsduck/params_merger"
 
 module JsDuck::Tag
-  class Event < Tag
+  class Event < MemberTag
     def initialize
       @pattern = "event"
       @tagname = :event
       @member_type = {
-        :name => :event,
-        :category => :method_like,
         :title => "Events",
         :position => MEMBER_POS_EVENT,
+        :icon => File.dirname(__FILE__) + "/icons/event.png"
       }
     end
 
@@ -24,5 +24,13 @@ module JsDuck::Tag
     def process_doc(h, tags, pos)
       h[:name] = tags[0][:name]
     end
+
+    def merge(h, docs, code)
+      JsDuck::ParamsMerger.merge(h, docs, code)
+    end
+
+    def to_html(event, cls)
+      member_link(event) + member_params(event[:params])
+    end
   end
 end

data/lib/jsduck/tag/extends.rb

@@ -8,7 +8,6 @@ module JsDuck::Tag
       @tagname = :extends
       @ext_define_pattern = "extend"
       @ext_define_default = {:extends => "Ext.Base"}
-      @merge_context = :class
     end
 
     # @extends classname
@@ -36,10 +35,5 @@ module JsDuck::Tag
       cls[:extends] = JsDuck::Js::Utils.make_string(ast)
     end
 
-    # Ignore extending of the Object class
-    def merge(h, docs, code)
-      h[:extends] = docs[:extends] || code[:extends]
-      h[:extends] = nil if h[:extends] == "Object"
-    end
   end
 end

data/lib/jsduck/tag/fires.rb

@@ -0,0 +1,53 @@
+require "jsduck/tag/tag"
+require "jsduck/logger"
+
+module JsDuck::Tag
+  class Fires < Tag
+    def initialize
+      @pattern = "fires"
+      @tagname = :fires
+      @repeatable = true
+      @html_position = POS_FIRES
+    end
+
+    # @fires eventname
+    def parse_doc(p, pos)
+      {:tagname => :fires, :events => ident_list(p)}
+    end
+
+    # matches <ident> <ident> ... until line end
+    def ident_list(p)
+      list = []
+      while ident = p.hw.ident
+        list << ident
+      end
+      list
+    end
+
+    def process_doc(h, tags, pos)
+      h[:fires] = tags.map {|t| t[:events] }.flatten
+    end
+
+    def format(m, formatter)
+      cls = formatter.relations[m[:owner]]
+
+      m[:fires] = m[:fires].map do |name|
+        if cls.find_members({:tagname => :event, :name => name}).length > 0
+          formatter.link(m[:owner], name, name, :event)
+        else
+          JsDuck::Logger.warn(:fires, "@fires references unknown event: #{name}", m[:files][0])
+          name
+        end
+      end
+    end
+
+    def to_html(m)
+      return [
+        "<h3 class='pa'>Fires</h3>",
+        "<ul>",
+          m[:fires].map {|e| "<li>#{e}</li>" },
+        "</ul>",
+      ]
+    end
+  end
+end

data/lib/jsduck/tag/member_tag.rb

@@ -0,0 +1,130 @@
+require 'jsduck/tag/tag'
+require 'jsduck/render/signature_util'
+
+module JsDuck::Tag
+  # Base class for all builtin members.
+  class MemberTag < Tag
+    # Defines a class member type and specifies various settings.  For
+    # example:
+    #
+    #     {
+    #       :title => "Events",
+    #       :position => MEMBER_POS_EVENT,
+    #       # The following are optional
+    #       :toolbar_title => "Events",
+    #       :icon => File.dirname(__FILE__) + "/icons/event.png",
+    #       :subsections => [
+    #         {:title => "Static events",
+    #          :filter => {:static => false},
+    #          :default => true},
+    #         {:title => "Instance events",
+    #          :filter => {:static => true}},
+    #       ]
+    #     }
+    #
+    # Position defines the ordering of member section in final HTML
+    # output.
+    #
+    # Title is shown at the top of each such section and also as a
+    # label on Docs app toolbar button unless :toolbar_title is
+    # specified.
+    #
+    # Icon defines a file to be used as member icon in various places
+    # of the docs app.
+    #
+    # Subsections allows splitting the list of members to several
+    # subgroups.  For example methods get split into static and
+    # instance methods.
+    #
+    # - The :filter field defines how to filter out the members for
+    #   this subcategory.  :static=>true filters out all members that
+    #   have a :static field with a truthy value.  Conversely,
+    #   :static=>false filters out members not having a :static field
+    #   or having it with a falsy value.
+    #
+    # - Setting :default=>true will hide the subsection title when all
+    #   the members end up in that subsection.  For example when there
+    #   are only instance methods, the docs will only contain the
+    #   section title "Methods", as by default one should assume all
+    #   methods are instance methods if not stated otherwise.
+    #
+    attr_reader :member_type
+
+    # Avoid already-defined-constant warnings in Ruby 1.8
+    unless defined?(MEMBER_POS_CFG)
+      MEMBER_POS_CFG = 1
+      MEMBER_POS_PROPERTY = 2
+      MEMBER_POS_METHOD = 3
+      MEMBER_POS_EVENT = 4
+      MEMBER_POS_CSS_VAR = 5
+      MEMBER_POS_CSS_MIXIN = 6
+    end
+
+    # Extracts the fields auto-detected from code that are relevant to
+    # the member type and returns a hash with them.
+    #
+    # The implementation here extracts fields applicable to all member
+    # types.  When additional member-specific fields are to be
+    # extracted, override this method, but be sure to call the
+    # superclass method too.
+    #
+    # For example inside Method tag we might additionally want to
+    # extract :type and :default:
+    #
+    #     def process_code(code)
+    #       h = super(code)
+    #       h[:type] = code[:type]
+    #       h[:default] = code[:default]
+    #       h
+    #     end
+    #
+    def process_code(code)
+      return {
+        :tagname => code[:tagname],
+        # An auto-detected name might be "MyClass.prototype.myMethod" -
+        # for member name we only want the last "myMethod" part.
+        :name => code[:name] ? code[:name].split(/\./).last : nil,
+
+        :autodetected => code[:autodetected],
+        :inheritdoc => code[:inheritdoc],
+        :static => code[:static],
+        :private => code[:private],
+        :inheritable => code[:inheritable],
+        :linenr => code[:linenr],
+      }
+    end
+
+    # Merges documentation and code hashes into the result hash.
+    def merge(hash, docs, code)
+    end
+
+    # This method defines the signature-line of the member.
+    # For example it might return something like this:
+    #
+    #     "apply(source, target) : Object"
+    #
+    # Use #member_link method to render the member name as link in a
+    # standard way.  Similarly there's helper method #member_params
+    # for rendering the parameter list.
+    def to_html(context, cls)
+    end
+
+    # Creates HTML link to the given member.
+    # A helper method for use in #to_html.
+    def member_link(member)
+      JsDuck::Render::SignatureUtil::link(member[:owner], member[:id], member[:name])
+    end
+
+    # Creates HTML listing of parameters.
+    # When called with nil, creates empty params list.
+    # A helper method for use in #to_html.
+    def member_params(params)
+      ps = Array(params).map do |p|
+        p[:optional] ? "["+p[:name]+"]" : p[:name]
+      end.join(", ")
+
+      "( <span class='pre'>#{ps}</span> )"
+    end
+
+  end
+end

data/lib/jsduck/tag/method.rb

@@ -1,16 +1,16 @@
-require "jsduck/tag/tag"
+require "jsduck/tag/member_tag"
+require "jsduck/params_merger"
 
 module JsDuck::Tag
   # Implementation of @method tag.
-  class Method < Tag
+  class Method < MemberTag
     def initialize
       @pattern = "method"
       @tagname = :method
       @member_type = {
-        :name => :method,
-        :category => :method_like,
         :title => "Methods",
         :position => MEMBER_POS_METHOD,
+        :icon => File.dirname(__FILE__) + "/icons/method.png",
         :subsections => [
           {:title => "Instance methods", :filter => {:static => false}, :default => true},
           {:title => "Static methods", :filter => {:static => true}},
@@ -31,5 +31,45 @@ module JsDuck::Tag
     def process_doc(h, tags, pos)
       h[:name] = tags[0][:name] if tags[0][:name]
     end
+
+    def process_code(code)
+      h = super(code)
+      h[:params] = code[:params]
+      h[:chainable] = code[:chainable]
+      h[:fires] = code[:fires]
+      h[:method_calls] = code[:method_calls]
+      h
+    end
+
+    def merge(h, docs, code)
+      JsDuck::ParamsMerger.merge(h, docs, code)
+    end
+
+    def to_html(m, cls)
+      new_kw(m) + method_link(m, cls) + member_params(m[:params]) + return_value(m)
+    end
+
+    private
+
+    def new_kw(m)
+      constructor?(m) ? "<strong class='new-keyword'>new</strong>" : ""
+    end
+
+    def method_link(m, cls)
+      if constructor?(m)
+        member_link(:owner => m[:owner], :id => m[:id], :name => cls[:name])
+      else
+        member_link(m)
+      end
+    end
+
+    def constructor?(m)
+      m[:name] == "constructor"
+    end
+
+    def return_value(m)
+      m[:return] ? (" : " + m[:return][:html_type]) : ""
+    end
+
   end
 end

data/lib/jsduck/tag/param.rb

@@ -1,8 +1,6 @@
 require "jsduck/tag/tag"
 require "jsduck/doc/subproperties"
 require "jsduck/render/subproperties"
-require "jsduck/docs_code_comparer"
-require "jsduck/logger"
 
 module JsDuck::Tag
   class Param < Tag
@@ -10,13 +8,18 @@ module JsDuck::Tag
       @pattern = "param"
       @tagname = :params
       @repeatable = true
-      @merge_context = :method_like
       @html_position = POS_PARAM
     end
 
     # @param {Type} [name=default] (optional) ...
     def parse_doc(p, pos)
-      tag = p.standard_tag({:tagname => :params, :type => true, :name => true})
+      tag = p.standard_tag({
+          :tagname => :params,
+          :type => true,
+          :name => true,
+          :default => true,
+          :optional => true
+        })
       tag[:optional] = true if parse_optional(p)
       tag[:doc] = :multiline
       tag
@@ -28,14 +31,7 @@ module JsDuck::Tag
 
     def process_doc(h, tags, pos)
       h[:params] = JsDuck::Doc::Subproperties.nest(tags, pos)
-    end
-
-    def merge(h, docs, code)
-      h[:params] = merge_params(docs, code, h[:files].first)
-
-      if only_autodetected_params?(docs, code)
-        JsDuck::DocsCodeComparer.mark_autodetected(h, :params)
-      end
+      h[:params] = nil if h[:params].length == 0
     end
 
     def format(m, formatter)
@@ -46,53 +42,5 @@ module JsDuck::Tag
       JsDuck::Render::Subproperties.render_params(m[:params]) if m[:params].length > 0
     end
 
-    private
-
-    def only_autodetected_params?(docs, code)
-      (docs[:params] || []).length == 0 && (code[:params] || []).length > 0
-    end
-
-    def merge_params(docs, code, file)
-      explicit = docs[:params] || []
-      implicit = JsDuck::DocsCodeComparer.matches?(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
-
-      # Override implicit parameters with explicit ones
-      # But if explicit ones exist, don't append the implicit ones.
-      params = []
-      (ex_len > 0 ? ex_len : im_len).times do |i|
-        im = implicit[i] || {}
-        ex = explicit[i] || {}
-        params << {
-          :type => ex[:type] || im[:type] || "Object",
-          :name => ex[:name] || im[:name] || "",
-          :doc => ex[:doc] || im[:doc] || "",
-          :optional => ex[:optional] || false,
-          :default => ex[:default],
-          :properties => ex[:properties] || [],
-        }
-      end
-      params
-    end
-
   end
 end