jsduck 3.2.1 → 3.3.0

data/Rakefile

@@ -163,12 +163,14 @@ class JsDuckRunner
   end
 
   # Enables comments when CORS is supported by browser.
-  # This excludes Opera and IE < 8
+  # This excludes Opera and IE < 8.
+  # We check explicitly for IE version to make sure the code works the
+  # same way in both real IE7 and IE7-mode of IE8/9.
   def add_comments(db_name)
     comments_base_url = "http://projects.sencha.com/auth"
     @options += ["--head-html", <<-EOHTML]
       <script type="text/javascript">
-        Docs.enableComments = ("withCredentials" in new XMLHttpRequest()) || (typeof XDomainRequest !== "undefined");
+        Docs.enableComments = ("withCredentials" in new XMLHttpRequest()) || (Ext.ieVersion >= 8);
         Docs.baseUrl = "#{comments_base_url}";
         Docs.commentsDb = "#{db_name}";
       </script>
@@ -220,10 +222,10 @@ class JsDuckRunner
 
   def set_touch2_src
     relative_touch_path = "../"
-    system("cp", "-r", "opt/touch-welcome.html", "template-min/touch-welcome.html")
-    system("cp", "-r", "opt/touch-iframe.html", "template-min/touch-iframe.html")
+    system("cp", "-r", "#{@sdk_dir}/touch/docs/welcome.html", "template-min/welcome.html")
+    system("cp", "-r", "#{@sdk_dir}/touch/docs/eg-iframe.html", "template-min/eg-iframe.html")
 
-    ["template-min/touch-iframe.html", "template-min/touch-welcome.html"].each do |file|
+    ["template-min/eg-iframe.html", "template-min/welcome.html"].each do |file|
       html = IO.read(file);
 
       touch_src_re = /((src|href)="touch)/m
@@ -245,8 +247,8 @@ class JsDuckRunner
 
     @options += [
       "--body-html", head_html,
-      "--welcome", "template-min/touch-welcome.html",
-      "--eg-iframe", "template-min/touch-iframe.html"
+      "--welcome", "template-min/welcome.html",
+      "--eg-iframe", "template-min/eg-iframe.html"
     ]
   end
 

data/bin/compare

@@ -32,9 +32,9 @@ end
 def compare_classes(cls1, cls2)
   diff = []
   cls1["members"].each_pair do |group_name, group_items|
-    group_items.find_all {|m1| !m1["private"] && !m1["protected"] && m1["owner"] == cls1["name"] }.each do |m1|
+    group_items.find_all {|m1| !m1["private"] && !m1["meta"]["protected"] && m1["owner"] == cls1["name"] }.each do |m1|
       match = cls2["members"][group_name].find do |m2|
-        m2["name"] == m1["name"] && !m2["protected"] && !m2["private"]
+        m2["name"] == m1["name"] && !m2["meta"]["protected"] && !m2["private"]
       end
       if !match && m1["name"] != "constructor" && m1["name"] != ""
         other = nil
@@ -47,9 +47,9 @@ def compare_classes(cls1, cls2)
           :name => m1["name"],
           :other => other ? {
             :type => other["tagname"],
-            :static => other["static"],
+            :static => other["meta"]["static"],
             :private => other["private"],
-            :protected => other["protected"],
+            :protected => other["meta"]["protected"],
           } : nil
         }
       end

data/js-classes/Date.js

@@ -227,7 +227,7 @@
  * @param {Number} min An integer between 0 and 59 representing the minutes.
  * @param {Number} sec An integer between 0 and 59 representing the seconds.
  * @param {Number} ms An integer between 0 and 999 representing the milliseconds.
- * @return {Date} Number of milliseconds since January 1, 1970, 00:00:00, universal time.
+ * @return {Number} Number of milliseconds since January 1, 1970, 00:00:00, universal time.
  */
 
 //Methods

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.2.1'
-  s.date = '2011-12-07'
+  s.version = '3.3.0'
+  s.date = '2012-01-04'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Documentation generator for Sencha JS frameworks"
   s.homepage = "https://github.com/senchalabs/jsduck"

data/lib/jsduck/accessors.rb

@@ -9,7 +9,7 @@ module JsDuck
     # not added.
     def create(cls)
       # Grab all configs tagged as @accessor
-      accessors = cls[:members][:cfg].find_all {|cfg| cfg[:accessor] && !cfg[:private] }
+      accessors = cls[:members][:cfg].find_all {|cfg| cfg[:accessor] }
 
       # Build lookup tables of method and event names
       methods = build_lookup_table(cls[:members][:method])
@@ -45,7 +45,7 @@ module JsDuck
 
     def create_getter(cfg)
       name = "get" + upcase_first(cfg[:name])
-      return {
+      return add_shared({
         :tagname => :method,
         :name => name,
         :doc => "Returns the value of {@link #cfg-#{cfg[:name]}}.",
@@ -54,16 +54,13 @@ module JsDuck
           :type => cfg[:type],
           :doc => "",
         },
-        :owner => cfg[:owner],
-        :files => cfg[:files],
         :id => "method-" + name,
-        :meta => clone_meta(cfg),
-      }
+      }, cfg)
     end
 
     def create_setter(cfg)
       name = "set" + upcase_first(cfg[:name]);
-      return {
+      return add_shared({
         :tagname => :method,
         :name => name,
         :doc => "Sets the value of {@link #cfg-#{cfg[:name]}}.",
@@ -76,17 +73,14 @@ module JsDuck
           :type => "undefined",
           :doc => "",
         },
-        :owner => cfg[:owner],
-        :files => cfg[:files],
         :id => "method-" + name,
-        :meta => clone_meta(cfg),
-      }
+      }, cfg)
     end
 
     def create_event(cfg)
       name = cfg[:name].downcase + "change"
       setter_name = "set" + upcase_first(cfg[:name]);
-      return {
+      return add_shared({
         :tagname => :event,
         :name => name,
         :doc =>
@@ -112,11 +106,17 @@ module JsDuck
             :doc => "The existing value."
           },
         ],
+        :id => "event-" + name,
+      }, cfg)
+    end
+
+    def add_shared(hash, cfg)
+      hash.merge!({
         :owner => cfg[:owner],
         :files => cfg[:files],
-        :id => "event-" + name,
+        :private => cfg[:private],
         :meta => clone_meta(cfg),
-      }
+      })
     end
 
     def upcase_first(str)
@@ -129,7 +129,7 @@ module JsDuck
     def clone_meta(cfg)
       h = {}
       cfg[:meta].each_pair do |key, value|
-        h[:key] = value unless key == :required
+        h[key] = value unless key == :required
       end
       h
     end

data/lib/jsduck/aggregator.rb

@@ -156,10 +156,9 @@ module JsDuck
         if orph[:owner]
           class_name = orph[:owner]
           if !@classes[class_name]
+            # this will add the class and add all orphans to it
             add_empty_class(class_name)
           end
-          add_member(orph)
-          @orphans.delete(orph)
         end
       end
     end

data/lib/jsduck/api_exporter.rb

@@ -19,7 +19,7 @@ module JsDuck
   # }
   #
   class ApiExporter
-    def initialize(relations, opts)
+    def initialize(relations)
       # All params ignored, they're present to be compatible with
       # other exporters.
     end

data/lib/jsduck/app_exporter.rb

@@ -1,19 +1,14 @@
 require 'jsduck/full_exporter'
 require 'jsduck/renderer'
 require 'jsduck/doc_formatter'
-require 'jsduck/meta_tag_registry'
 
 module JsDuck
 
   # Exports data for Docs app.
   class AppExporter < FullExporter
-    def initialize(relations, opts)
-      super(relations, opts)
-
+    def initialize(relations)
+      super(relations)
       @renderer = Renderer.new
-      # Inject formatter to all meta-tags.
-      doc_formatter = DocFormatter.new(relations, opts)
-      MetaTagRegistry.instance.formatter = doc_formatter
     end
 
     # Returns compacted class data hash which contains an additional

data/lib/jsduck/class.rb

@@ -124,7 +124,7 @@ module JsDuck
       all_members = parent ? parent.members_hash(type, context) : {}
 
       mixins.each do |mix|
-        all_members.merge!(mix.members_hash(type, context))
+        all_members.merge!(mix.members_hash(type, context)) {|k,o,n| store_overrides(k,o,n)}
       end
 
       # For static members, exclude everything not explicitly marked as inheritable
@@ -132,19 +132,38 @@ module JsDuck
         all_members.delete_if {|key, member| !member[:inheritable] }
       end
 
-      all_members.merge!(local_members_hash(type, context))
+      all_members.merge!(local_members_hash(type, context)) {|k,o,n| store_overrides(k,o,n)}
 
       # If singleton has static members, include them as if they were
       # instance members.  Otherwise they will be completely excluded
       # from the docs, as the static members block is not created for
       # singletons.
       if @doc[:singleton] && @doc[:statics][type].length > 0
-        all_members.merge!(local_members_hash(type, :statics))
+        all_members.merge!(local_members_hash(type, :statics)) {|k,o,n| store_overrides(k,o,n)}
       end
 
       all_members
     end
 
+    # Invoked when merge! finds two members with the same name.
+    # New member always overrides the old, but inside new we keep
+    # a list of members it overrides.  Normally one member will
+    # override one other member, but a member from mixin can override
+    # multiple members - although there's not a single such case in
+    # ExtJS, we have to handle it.
+    #
+    # Every overridden member is listed just once.
+    def store_overrides(key, old, new)
+      # Sometimes a class is included multiple times (like Ext.Base)
+      # resulting in its members overriding themselves.  Because of
+      # this, ignore overriding itself.
+      if new[:owner] != old[:owner]
+        new[:overrides] = [] unless new[:overrides]
+        new[:overrides] << old unless new[:overrides].any? {|m| m[:owner] == old[:owner] }
+      end
+      new
+    end
+
     # Helper method to get the direct members of this class
     def local_members_hash(type, context)
       local_members = {}

data/lib/jsduck/class_formatter.rb

@@ -1,5 +1,6 @@
 require 'jsduck/type_parser'
 require 'jsduck/logger'
+require 'jsduck/meta_tag_registry'
 
 module JsDuck
 
@@ -13,6 +14,8 @@ module JsDuck
     def initialize(relations, formatter)
       @relations = relations
       @formatter = formatter
+      # inject formatter to all meta-tags
+      MetaTagRegistry.instance.formatter = formatter
       @include_types = true
     end
 
@@ -23,12 +26,15 @@ module JsDuck
       @formatter.class_context = cls[:name]
       @formatter.doc_context = cls[:files][0]
       cls[:doc] = @formatter.format(cls[:doc]) if cls[:doc]
-      cls[:members].each_pair do |type, members|
-        cls[:members][type] = members.reject {|m| m[:private] }.map {|m| format_member(m) }
-      end
-      cls[:statics].each_pair do |type, members|
-        cls[:statics][type] = members.reject {|m| m[:private] }.map {|m| format_member(m) }
+      [:members, :statics].each do |group|
+        cls[group].each_pair do |type, members|
+          # format all public members, but keep the private members
+          # too - some of them might override public members and we
+          # don't want to lose this information.
+          cls[group][type] = members.map {|m| m[:private] ? m : format_member(m)  }
+        end
       end
+      cls[:html_meta] = format_meta_data(cls[:meta])
       cls
     end
 
@@ -46,6 +52,7 @@ module JsDuck
       m[:params] = m[:params].map {|p| format_item(p, is_css_tag) } if m[:params]
       m[:return] = format_item(m[:return], is_css_tag) if m[:return]
       m[:properties] = m[:properties].map {|b| format_item(b, is_css_tag) } if m[:properties]
+      m[:html_meta] = format_meta_data(m[:meta])
       m
     end
 
@@ -75,6 +82,14 @@ module JsDuck
       end
     end
 
+    def format_meta_data(meta_data)
+      result = {}
+      meta_data.each_pair do |key, value|
+        result[key] = MetaTagRegistry.instance[key].to_html(value) if value
+      end
+      result
+    end
+
   end
 
 end

data/lib/jsduck/class_writer.rb

@@ -9,7 +9,7 @@ module JsDuck
   class ClassWriter
     def initialize(exporter_class, relations, opts)
       @relations = relations
-      @exporter = exporter_class.new(relations, opts)
+      @exporter = exporter_class.new(relations)
       @parallel = ParallelWrap.new(:in_processes => opts.processes)
     end
 

data/lib/jsduck/full_exporter.rb

@@ -4,7 +4,7 @@ module JsDuck
 
   # Exporter for all the class docs.
   class FullExporter
-    def initialize(relations, opts)
+    def initialize(relations)
       @relations = relations
     end
 

data/lib/jsduck/js_parser.rb

@@ -73,9 +73,9 @@ module JsDuck
     # <code-block> := <function> | <var-declaration> | <ext-define> |
     #                 <assignment> | <property-literal>
     def code_block
-      if look("function")
+      if look(:function)
         function
-      elsif look("var")
+      elsif look(:var)
         var_declaration
       elsif ext_look(:ns, ".", "define", "(", :string)
         ext_define
@@ -86,7 +86,7 @@ module JsDuck
       elsif look(",", :ident, ":") || look(",", :string, ":")
         match(",")
         property_literal
-      elsif look(:ident) || look("this")
+      elsif look(:ident) || look(:this)
         maybe_assignment
       elsif look(:string)
         {:type => :assignment, :left => [match(:string)[:value]]}
@@ -97,15 +97,25 @@ module JsDuck
 
     # <function> := "function" [ <ident> ] <function-parameters> <function-body>
     def function
-      match("function")
+      match(:function)
       return {
         :type => :function,
-        :name => look(:ident) ? match(:ident)[:value] : nil,
+        :name => look(:ident) ? match(:ident)[:value] : "",
         :params => function_parameters,
         :body => function_body,
       }
     end
 
+    # <ext-emptyfn> := "Ext" "." "emptyFn"
+    def ext_emptyfn
+      match(:ident, ".", "emptyFn")
+      return {
+        :type => :function,
+        :name => "",
+        :params => [],
+      }
+    end
+
     # <function-parameters> := "(" [ <ident> [ "," <ident> ]* ] ")"
     def function_parameters
       match("(")
@@ -124,7 +134,7 @@ module JsDuck
 
     # <var-declaration> := "var" <assignment>
     def var_declaration
-      match("var")
+      match(:var)
       maybe_assignment
     end
 
@@ -144,8 +154,9 @@ module JsDuck
 
     # <ident-chain> := [ "this" | <ident> ]  [ "." <ident> ]*
     def ident_chain
-      if look("this")
-        chain = [match("this")[:value]]
+      if look(:this)
+        match(:this)
+        chain = ["this"]
       else
         chain = [match(:ident)[:value]]
       end
@@ -156,12 +167,14 @@ module JsDuck
       return chain
     end
 
-    # <expression> := <function> | <ext-extend> | <ext-base-css-prefix> | <literal>
+    # <expression> := <function> | <ext-extend> | <ext-emptyfn> | <ext-base-css-prefix> | <literal>
     def expression
-      if look("function")
+      if look(:function)
         function
       elsif ext_look(:ns, ".", "extend")
         ext_extend
+      elsif ext_look(:ns, ".", "emptyFn")
+        ext_emptyfn
       elsif ext_look(:ns, ".", "baseCSSPrefix", "+", :string)
         ext_base_css_prefix
       else

data/lib/jsduck/lexer.rb

@@ -9,12 +9,14 @@ module JsDuck
   #
   # - :number      -- 25
   # - :string      -- "Hello world"
-  # - :keyword     -- "typeof"
   # - :ident       -- "foo"
   # - :regex       -- "/abc/i"
   # - :operator    -- "+"
   # - :doc_comment -- "/** My comment */"
   #
+  # Plus a separate types for all keywords: :if, :while, :function, ...
+  # For keywords the type and value are the same.
+  #
   # Notice that doc-comments are recognized as tokens while normal
   # comments are ignored just as whitespace.
   #
@@ -120,9 +122,10 @@ module JsDuck
           }
         elsif @input.check(/[a-zA-Z_$]/)
           value = @input.scan(/[$\w]+/)
+          kw = KEYWORDS[value]
           return {
-            :type => KEYWORDS[value] ? :keyword : :ident,
-            :value => value
+            :type => kw || :ident,
+            :value => kw || value
           }
         elsif @input.check(/'/)
           return {
@@ -189,7 +192,7 @@ module JsDuck
         value = @previous_token[:value]
         if type == :ident || type == :number
           return false
-        elsif type == :keyword && value == "this"
+        elsif type == :this
           return false
         elsif type == :operator && (value == ")" || value == "]")
           return false
@@ -217,31 +220,31 @@ module JsDuck
     }x
 
     KEYWORDS = {
-      "break" => true,
-      "case" => true,
-      "catch" => true,
-      "continue" => true,
-      "default" => true,
-      "delete" => true,
-      "do" => true,
-      "else" => true,
-      "finally" => true,
-      "for" => true,
-      "function" => true,
-      "if" => true,
-      "in" => true,
-      "instanceof" => true,
-      "new" => true,
-      "return" => true,
-      "switch" => true,
-      "this" => true,
-      "throw" => true,
-      "try" => true,
-      "typeof" => true,
-      "var" => true,
-      "void" => true,
-      "while" => true,
-      "with" => true,
+      "break" => :break,
+      "case" => :case,
+      "catch" => :catch,
+      "continue" => :continue,
+      "default" => :default,
+      "delete" => :delete,
+      "do" => :do,
+      "else" => :else,
+      "finally" => :finally,
+      "for" => :for,
+      "function" => :function,
+      "if" => :if,
+      "in" => :in,
+      "instanceof" => :instanceof,
+      "new" => :new,
+      "return" => :return,
+      "switch" => :switch,
+      "this" => :this,
+      "throw" => :throw,
+      "try" => :try,
+      "typeof" => :typeof,
+      "var" => :var,
+      "void" => :void,
+      "while" => :while,
+      "with" => :with,
     }
   end
 

data/lib/jsduck/lint.rb

@@ -17,6 +17,7 @@ module JsDuck
       warn_unnamed
       warn_optional_params
       warn_duplicate_params
+      warn_duplicate_members
     end
 
     # print warning for each global member
@@ -84,6 +85,25 @@ module JsDuck
       end
     end
 
+    # print warnings for duplicate member names
+    def warn_duplicate_members
+      @relations.each do |cls|
+        members = {:members => {}, :statics => {}}
+        cls.all_local_members.each do |m|
+          group = (m[:meta] && m[:meta][:static]) ? :statics : :members
+          type = m[:tagname]
+          name = m[:name]
+          hash = members[group][type] || {}
+          if hash[name]
+            warn(:dup_member, "Duplicate #{type} name #{name}", hash[name])
+            warn(:dup_member, "Duplicate #{type} name #{name}", m)
+          end
+          hash[name] = m
+          members[group][type] = hash
+        end
+      end
+    end
+
     # Loops through all members of all classes
     def each_member(&block)
       @relations.each {|cls| cls.all_local_members.each(&block) }

data/lib/jsduck/logger.rb

@@ -24,7 +24,8 @@ module JsDuck
         [:alt_name, "Name used as both classname and alternate classname"],
         [:name_missing, "Member or parameter has no name"],
         [:no_doc, "Member or class without documentation"],
-        [:dup_param, "Method has two parameters with same name"],
+        [:dup_param, "Method has two parameters with the same name"],
+        [:dup_member, "Class has two members with the same name"],
         [:req_after_opt, "Required parameter comes after optional"],
         [:subproperty, "@param foo.bar where foo param doesn't exist"],
         [:sing_static, "Singleton class member marked as @static"],

data/lib/jsduck/merger.rb

@@ -52,6 +52,9 @@ module JsDuck
         :property
       elsif doc_map[:css_var]
         :css_var
+      elsif doc_map[:cfg] && doc_map[:cfg].length == 1
+        # When just one @cfg, avoid treating it as @class
+        :cfg
       elsif code[:type] == :ext_define
         :class
       elsif code[:type] == :assignment && class_name?(*code[:left])

data/lib/jsduck/options.rb

@@ -71,7 +71,7 @@ module JsDuck
       ]
       @meta_tag_paths = []
 
-      @version = "3.2.1"
+      @version = "3.3.0"
 
       # Customizing output
       @title = "Sencha Docs - Ext JS"

data/lib/jsduck/renderer.rb

@@ -9,17 +9,13 @@ module JsDuck
     def render(cls)
         @cls = cls
 
-        # Set doc-formatter context to this class
-        MetaTagRegistry.instance.formatter.class_context = @cls[:name]
-        MetaTagRegistry.instance.formatter.doc_context = @cls[:files][0]
-
         return [
           "<div>",
             render_sidebar,
             "<div class='doc-contents'>",
               render_private_class_notice,
               @cls[:doc],
-              render_meta_data(@cls[:meta]),
+              render_meta_data(@cls[:html_meta]),
             "</div>",
             "<div class='members'>",
               render_member_sections,
@@ -40,14 +36,7 @@ module JsDuck
     def render_meta_data(meta_data)
       return if meta_data.size == 0
 
-      MetaTagRegistry.instance.tags.map do |tag|
-        contents = meta_data[tag.key]
-        if contents
-          tag.to_html(contents)
-        else
-          nil
-        end
-      end
+      MetaTagRegistry.instance.tags.map {|tag| meta_data[tag.key] }
     end
 
     def render_sidebar
@@ -120,8 +109,10 @@ module JsDuck
       ]
     end
 
-    def render_link(cls_name)
-        return "<a href='#!/api/#{cls_name}' rel='#{cls_name}' class='docClass'>#{cls_name}</a>"
+    def render_link(cls_name, member=nil)
+      id = member ? cls_name + "-" + member[:id] : cls_name
+      label = member ? cls_name + "." + member[:name] : cls_name
+      return "<a href='#!/api/#{id}' rel='#{id}' class='docClass'>#{label}</a>"
     end
 
     def render_member_sections
@@ -249,11 +240,15 @@ module JsDuck
         doc << "<p>Defaults to: <code>" + CGI.escapeHTML(m[:default]) + "</code></p>"
       end
 
-      MetaTagRegistry.instance.formatter.doc_context = m[:files][0]
-      doc << render_meta_data(m[:meta])
+      doc << render_meta_data(m[:html_meta])
 
       doc << render_params_and_return(m)
 
+      if m[:overrides]
+        overrides = m[:overrides].map {|o| render_link(o[:owner], o) }.join(", ")
+        doc << "<p>Overrides: #{overrides}</p>"
+      end
+
       doc
     end
 

data/lib/jsduck/tag/template.rb

@@ -13,7 +13,8 @@ module JsDuck::Tag
     def to_html(contents)
       <<-EOHTML
       <div class='signature-box template'>
-      <p>This is a template method. A hook into the functionality of this class.
+      <p>This is a <a href="#!/guide/components">template method</a>.
+         a hook into the functionality of this class.
          Feel free to override it in child classes.</p>
       </div>
       EOHTML

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: jsduck
 version: !ruby/object:Gem::Version 
-  hash: 13
+  hash: 11
   prerelease: false
   segments: 
   - 3
-  - 2
-  - 1
-  version: 3.2.1
+  - 3
+  - 0
+  version: 3.3.0
 platform: ruby
 authors: 
 - Rene Saarsoo
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-12-07 00:00:00 +02:00
+date: 2012-01-04 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency