jsduck 0.3 → 0.4

data/README.md

@@ -195,6 +195,12 @@ JsDuck was developed by [Rene Saarsoo](http://triin.net).
 Changelog
 ---------
 
+* 0.4 - Ext4 support
+  * Support for Ext.define() syntax from ExtJS 4.
+  * Showing @xtype and @author information on generated pages.
+  * Showing filename and line number in warnings.
+  * Fix for event showing the same doc as method with same name.
+
 * 0.3 - Performance improvements
   * Significant peed improvements - most importantly utilizing
     multiple CPU-s (if available) to speed things up.  On my 4-core

data/jsduck.gemspec

@@ -2,8 +2,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = ">= 1.3.7"
 
   s.name = 'jsduck'
-  s.version = '0.3'
-  s.date = '2011-02-08'
+  s.version = '0.4'
+  s.date = '2011-02-28'
   s.summary = "Simple JavaScript Duckumentation generator"
   s.description = "Better ext-doc like JavaScript documentation generator for ExtJS"
   s.homepage = "https://github.com/nene/jsduck"

data/lib/jsduck/aggregator.rb

@@ -24,21 +24,28 @@ module JsDuck
     def aggregate(input, filename="", html_filename="")
       @current_class = nil
       input.each do |docset|
-        doc = docset[:comment]
-        code = docset[:code]
-        href = html_filename + "#line-" + docset[:linenr].to_s
-        register(add_href(@merger.merge(doc, code), href, filename))
+        doc = @merger.merge(docset[:comment], docset[:code])
+
+        add_source_data(doc, {
+          :filename => filename,
+          :html_filename => html_filename,
+          :linenr => docset[:linenr],
+        })
+
+        register(doc)
       end
     end
 
-    # Tags doc-object with link to source code where it came from.
-    # For class we also store the name of the JavaScript file.
-    def add_href(doc, href, filename)
-      doc[:href] = href
+    # Links doc-object to source code where it came from.
+    def add_source_data(doc, src)
+      doc[:href] = src[:html_filename] + "#line-" + src[:linenr].to_s
+      doc[:filename] = src[:filename]
+      doc[:linenr] = src[:linenr]
+      # class-level doc-comment can contain constructor and config
+      # options, link those to the same location in source.
       if doc[:tagname] == :class
-        doc[:filename] = filename
-        doc[:cfg].each {|cfg| cfg[:href] = href }
-        doc[:method].each {|method| method[:href] = href }
+        doc[:cfg].each {|cfg| add_source_data(cfg, src) }
+        doc[:method].each {|method| add_source_data(method, src) }
       end
       doc
     end

data/lib/jsduck/app.rb

@@ -50,8 +50,8 @@ module JsDuck
         puts "Parsing #{fname} ..." if @verbose
         code = IO.read(fname)
         {
-          :name => fname,
-          :src_name => src.write(code, fname),
+          :filename => fname,
+          :html_filename => File.basename(src.write(code, fname)),
           :data => Parser.new(code).parse,
         }
       end
@@ -61,8 +61,8 @@ module JsDuck
     def aggregate(parsed_files)
       agr = Aggregator.new
       parsed_files.each do |file|
-        puts "Aggregating #{file[:name]} ..." if @verbose
-        agr.aggregate(file[:data], File.basename(file[:name]), File.basename(file[:src_name]))
+        puts "Aggregating #{file[:filename]} ..." if @verbose
+        agr.aggregate(file[:data], file[:filename], file[:html_filename])
       end
       agr.result
     end
@@ -75,7 +75,11 @@ module JsDuck
         if d[:tagname] == :class
           classes[d[:name]] = Class.new(d, classes)
         else
-          puts "Warning: Ignoring " + d[:tagname].to_s + ": " + (d[:name] || "")
+          type = d[:tagname].to_s
+          name = d[:name]
+          file = d[:filename]
+          line = d[:linenr]
+          puts "Warning: Ignoring #{type}: #{name} in #{file} line #{line}"
         end
       end
       classes.values

data/lib/jsduck/class.rb

@@ -18,6 +18,12 @@ module JsDuck
       @doc[:extends] ? @classes[@doc[:extends]] : nil
     end
 
+    # Returns array of mixin class instances.
+    # Returns empty array if no mixins
+    def mixins
+      @doc[:mixins] ? @doc[:mixins].collect {|classname| @classes[classname] } : []
+    end
+
     # Returns true when this class inherits from the specified class.
     # Also returns true when the class itself is the one we are asking about.
     def inherits_from?(class_name)
@@ -51,9 +57,9 @@ module JsDuck
       ms
     end
 
-    # Returns hash of public members of class (and parent classes).
-    # Members are methods, properties, cfgs, events (member type
-    # is speified through 'type' parameter).
+    # Returns hash of public members of class (and of parent classes
+    # and mixin classes).  Members are methods, properties, cfgs,
+    # events (member type is specified through 'type' parameter).
     #
     # When parent and child have members with same name,
     # member from child overrides tha parent member.
@@ -61,11 +67,17 @@ module JsDuck
     # We also set :member property to each member to the full class
     # name where it belongs, so one can tell them apart afterwards.
     def members_hash(type)
-      parent_members = parent ? parent.members_hash(type) : {}
+      all_members = parent ? parent.members_hash(type) : {}
+
+      mixins.each do |mix|
+        all_members.merge!(mix.members_hash(type))
+      end
+
       @doc[type].each do |m|
-        parent_members[m[:name]] = m if !m[:private]
+        all_members[m[:name]] = m if !m[:private]
       end
-      parent_members
+
+      all_members
     end
 
     # A way to access full class name with similar syntax to

data/lib/jsduck/doc_parser.rb

@@ -90,10 +90,15 @@ module JsDuck
           at_xtype
         elsif look(/@member\b/)
           at_member
+        elsif look(/@author\b/)
+          at_author
         elsif look(/@static\b/)
           boolean_at_tag(/@static/, :static)
         elsif look(/@(private|ignore|hide|protected)\b/)
           boolean_at_tag(/@(private|ignore|hide|protected)/, :private)
+        elsif look(/@markdown\b/)
+          # this is detected just to be ignored
+          boolean_at_tag(/@markdown/, :markdown)
         elsif look(/@/)
           @current_tag[:doc] += @input.scan(/@/)
         elsif look(/[^@]/)
@@ -207,6 +212,15 @@ module JsDuck
       skip_white
     end
 
+    # matches @author some name ... newline
+    def at_author
+      match(/@author/)
+      add_tag(:author)
+      skip_horiz_white
+      @current_tag[:name] = @input.scan(/.*$/)
+      skip_white
+    end
+
     # Used to match @private, @ignore, @hide, ...
     def boolean_at_tag(regex, propname)
       match(regex)

data/lib/jsduck/event_table.rb

@@ -11,7 +11,7 @@ module JsDuck
       @id = @cls.full_name + "-events"
       @title = "Public Events"
       @column_title = "Event"
-      @row_class = "method-row"
+      @row_class = "event-row"
       @short_params = ShortParams.new
       @long_params = LongParams.new(@cls)
     end

data/lib/jsduck/merger.rb

@@ -33,7 +33,7 @@ module JsDuck
         :method
       elsif doc_map[:property] || doc_map[:type]
         :property
-      elsif code[:type] == :ext_extend
+      elsif code[:type] == :ext_define
         :class
       elsif code[:type] == :assignment && class_name?(*code[:left])
         :class
@@ -109,7 +109,9 @@ module JsDuck
         :name => detect_name(:class, doc_map, code, :full_name),
         :doc => detect_doc(docs),
         :extends => detect_extends(doc_map, code),
+        :mixins => detect_mixins(doc_map, code),
         :xtype => detect_xtype(doc_map),
+        :author => detect_author(doc_map),
         :singleton => !!doc_map[:singleton],
         :private => !!doc_map[:private],
       }
@@ -176,6 +178,8 @@ module JsDuck
         code[:name]
       elsif code[:type] == :assignment
         name_type == :full_name ? code[:left].join(".") : code[:left].last
+      elsif code[:type] == :ext_define
+        name_type == :full_name ? code[:name] : code[:name].split(/\./).last
       else
         ""
       end
@@ -215,6 +219,16 @@ module JsDuck
         doc_map[:extends].first[:extends]
       elsif code[:type] == :assignment && code[:right] && code[:right][:type] == :ext_extend
         code[:right][:extend].join(".")
+      elsif code[:type] == :ext_define
+        code[:extend]
+      end
+    end
+
+    def detect_mixins(doc_map, code)
+      if code[:type] == :ext_define && code[:mixins]
+        code[:mixins]
+      else
+        []
       end
     end
 
@@ -222,6 +236,10 @@ module JsDuck
       doc_map[:xtype] ? doc_map[:xtype].first[:name] : nil
     end
 
+    def detect_author(doc_map)
+      doc_map[:author] ? doc_map[:author].first[:name] : nil
+    end
+
     def detect_params(docs, code)
       implicit = detect_implicit_params(code)
       explicit = detect_explicit_params(docs)

data/lib/jsduck/page.rb

@@ -51,8 +51,11 @@ module JsDuck
       [
        "<table cellspacing='0'>",
         abstract_row("Extends:", @cls.parent ? class_link(@cls.parent.full_name) : "Object"),
+        @cls.mixins.length > 0 ? abstract_row("Mixins:", mixins) : "",
         abstract_row("Defind In:", file_link),
         @subclasses[@cls] ? abstract_row("Subclasses:", subclasses) : "",
+        @cls[:xtype] ? abstract_row("xtype:", @cls[:xtype]) : "",
+        @cls[:author] ? abstract_row("Author:", @cls[:author]) : "",
        "</table>",
       ].join("\n")
     end
@@ -63,7 +66,7 @@ module JsDuck
     end
 
     def file_link
-      "<a href='source/#{@cls[:href]}'>#{@cls[:filename]}</a>"
+      "<a href='source/#{@cls[:href]}'>#{File.basename(@cls[:filename])}</a>"
     end
 
     def subclasses
@@ -71,6 +74,11 @@ module JsDuck
       subs.collect {|cls| class_link(cls.full_name, cls.short_name) }.join(", ")
     end
 
+    def mixins
+      mixs = @cls.mixins.sort {|a, b| a.full_name <=> b.full_name }
+      mixs.collect {|cls| class_link(cls.full_name, cls.short_name) }.join(", ")
+    end
+
     def abstract_row(label, info)
       "<tr><td class='label'>#{label}</td><td class='hd-info'>#{info}</td></tr>"
     end

data/lib/jsduck/parser.rb

@@ -67,12 +67,15 @@ module JsDuck
     # The following is a recursive-descent parser for JavaScript that
     # can possibly follow a doc-comment
 
-    # <code-block> := <function> | <var-declaration> | <assignment> | <property-literal>
+    # <code-block> := <function> | <var-declaration> | <ext-define> |
+    #                 <assignment> | <property-literal>
     def code_block
       if look("function")
         function
       elsif look("var")
         var_declaration
+      elsif look("Ext", ".", "define", "(", :string)
+        ext_define
       elsif look(:ident, ":") || look(:string, ":")
         property_literal
       elsif look(",", :ident, ":") || look(",", :string, ":")
@@ -175,6 +178,87 @@ module JsDuck
       }
     end
 
+    # <ext-define> := "Ext" "." "define" "(" <string> "," <ext-define-cfg>
+    def ext_define
+      name = match("Ext", ".", "define", "(", :string)
+
+      if look(",", "{")
+        match(",")
+        cfg = ext_define_cfg
+      else
+        cfg = {}
+      end
+
+      cfg[:type] = :ext_define
+      cfg[:name] = name
+
+      cfg
+    end
+
+    # <ext-define-cfg> := "{" ( <extend> | <mixins> | <?> )*
+    def ext_define_cfg
+      match("{")
+      cfg = {}
+      found = true
+      while found
+        found = false
+        if look("extend", ":", :string)
+          cfg[:extend] = ext_define_extend
+          found = true
+        elsif look("mixins", ":", "{")
+          cfg[:mixins] = ext_define_mixins
+          found = true
+        elsif look(:ident, ":")
+          match(:ident, ":")
+          if look(:string) || look(:number) || look(:regex) ||
+              look("true") || look("false") ||
+              look("null") || look("undefined")
+            # Some key with literal value -- ignore
+            @lex.next
+            found = true
+          elsif look("[")
+            # Some key with array of strings -- ignore
+            found = array_of_strings
+          end
+        end
+        match(",") if look(",")
+      end
+      cfg
+    end
+
+    # <ext-define-extend> := "extend" ":" <string>
+    def ext_define_extend
+      match("extend", ":", :string)
+    end
+
+    # <ext-define-mixins> := "mixins" ":" "{" [ <ident> ":" <string> ","? ]* "}"
+    def ext_define_mixins
+      match("mixins", ":", "{")
+      mixins = []
+      while look(:ident, ":", :string)
+        mixins << match(:ident, ":", :string)
+        match(",") if look(",")
+      end
+      match("}") if look("}")
+      mixins
+    end
+
+    # <array-of-strings> := "[" [ <string> ","? ]* "]"
+    def array_of_strings
+      match("[")
+      while look(:string)
+        match(:string)
+        match(",") if look(",")
+      end
+
+      if look("]")
+        match("]")
+        true
+      else
+        false
+      end
+    end
+
     # <property-literal> := ( <ident> | <string> ) ":" <expression>
     def property_literal
       left = look(:ident) ? match(:ident) : match(:string)

metadata

@@ -1,12 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: jsduck
 version: !ruby/object:Gem::Version 
-  hash: 13
+  hash: 3
   prerelease: false
   segments: 
   - 0
-  - 3
-  version: "0.3"
+  - 4
+  version: "0.4"
 platform: ruby
 authors: 
 - Rene Saarsoo
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-08 00:00:00 +02:00
+date: 2011-02-28 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency