jsduck 3.0.1 → 3.1.0

data/lib/jsduck/merger.rb

@@ -103,7 +103,7 @@ module JsDuck
           end
         end
 
-        if tag[:tagname] == :xtype
+        if tag[:tagname] == :alias
           groups[:class] << tag
         elsif group_name == :cfg
           groups[:cfg].last << tag
@@ -123,8 +123,7 @@ module JsDuck
         :extends => detect_extends(doc_map, code),
         :mixins => detect_list(:mixins, doc_map, code),
         :alternateClassNames => detect_list(:alternateClassNames, doc_map, code),
-        :xtypes => detect_xtypes(doc_map, code),
-        :meta => detect_meta(doc_map),
+        :aliases => detect_aliases(doc_map, code),
         :singleton => detect_singleton(doc_map, code),
         :requires => detect_list(:requires, doc_map, code),
         :uses => detect_list(:uses, doc_map, code),
@@ -227,7 +226,8 @@ module JsDuck
         :static => !!doc_map[:static],
         :inheritable => !!doc_map[:inheritable],
         :deprecated => detect_deprecated(doc_map),
-        :alias => doc_map[:alias] ? doc_map[:alias].first : nil,
+        :inheritdoc => doc_map[:inheritdoc] ? doc_map[:inheritdoc].first : nil,
+        :meta => detect_meta(doc_map),
       })
       hash[:id] = create_member_id(hash)
       return hash
@@ -330,31 +330,35 @@ module JsDuck
       end
     end
 
-    def detect_xtypes(doc_map, code)
-      if doc_map[:xtype]
-        {"widget" => doc_map[:xtype].map {|tag| tag[:name] } }
+    def detect_aliases(doc_map, code)
+      if doc_map[:alias]
+        build_aliases_hash(doc_map[:alias].map {|tag| tag[:name] })
       elsif code[:xtype] || code[:alias]
-        xtypes = {}
-        (code[:xtype] || []).each do |a|
-          if xtypes["widget"]
-            xtypes["widget"] << a
+        hash = {}
+        build_aliases_hash(code[:xtype].map {|xtype| "widget."+xtype }, hash) if code[:xtype]
+        build_aliases_hash(code[:alias], hash) if code[:alias]
+        hash
+      else
+        {}
+      end
+    end
+
+    # Given array of full alias names like "foo.bar", "foo.baz"
+    # build hash like {"foo" => ["bar", "baz"]}
+    #
+    # When hash given as second argument, then merges the aliases into
+    # it instead of creating a new hash.
+    def build_aliases_hash(aliases, hash={})
+      aliases.each do |a|
+        if a =~ /^([\w.]+)\.(\w+)$/
+          if hash[$1]
+            hash[$1] << $2
           else
-            xtypes["widget"] = [a]
-          end
-        end
-        (code[:alias] || []).each do |a|
-          if a =~ /^([\w.]+)\.(\w+)$/
-            if xtypes[$1]
-              xtypes[$1] << $2
-            else
-              xtypes[$1] = [$2]
-            end
+            hash[$1] = [$2]
           end
         end
-        xtypes
-      else
-        {}
       end
+      hash
     end
 
     def detect_meta(doc_map)
@@ -437,7 +441,7 @@ module JsDuck
             parent[:properties] = [] unless parent[:properties]
             parent[:properties] << it
           else
-            Logger.instance.warn("Ignoring subproperty #{$1}.#{$2}, no parent found with name '#{$1}'.", @filename, @linenr)
+            Logger.instance.warn(:subproperty, "Ignoring subproperty #{$1}.#{$2}, no parent found with name '#{$1}'.", @filename, @linenr)
           end
         else
           items << it

data/lib/jsduck/null_object.rb

@@ -0,0 +1,19 @@
+module JsDuck
+  # A class that does nothing.
+  # Responds to all methods by returning self, unless a hash passed to
+  # constructor.
+  # See: http://en.wikipedia.org/wiki/Null_Object_pattern
+  class NullObject
+    # Optionally takes a hash of method_name => return_value pairs,
+    # making it return those values for those methods, sort of like
+    # OpenStruct, but for all other methods self is still returned and
+    # any number of arguments is accepted.
+    def initialize(methods={})
+      @methods = methods
+    end
+
+    def method_missing(meth, *args, &block)
+      @methods.has_key?(meth) ? @methods[meth] : self
+    end
+  end
+end

data/lib/jsduck/options.rb

@@ -1,5 +1,6 @@
 require 'optparse'
 require 'jsduck/meta_tag_loader'
+require 'jsduck/logger'
 
 module JsDuck
 
@@ -11,8 +12,6 @@ module JsDuck
     attr_accessor :ignore_global
     attr_accessor :external_classes
     attr_accessor :meta_tags
-    attr_accessor :warnings
-    attr_accessor :verbose
 
     # Customizing output
     attr_accessor :title
@@ -24,6 +23,7 @@ module JsDuck
     attr_accessor :guides
     attr_accessor :videos
     attr_accessor :examples
+    attr_accessor :stats
     attr_accessor :categories_path
     attr_accessor :pretty_json
     attr_accessor :images
@@ -73,9 +73,7 @@ module JsDuck
       @meta_tags = []
       @meta_tag_paths = []
 
-      @warnings = true
-      @verbose = false
-      @version = "3.0.1"
+      @version = "3.1.0"
 
       # Customizing output
       @title = "Sencha Docs - Ext JS"
@@ -87,6 +85,7 @@ module JsDuck
       @guides = nil
       @videos = nil
       @examples = nil
+      @stats = false
       @categories_path = nil
       @pretty_json = false
       @images = []
@@ -130,8 +129,9 @@ module JsDuck
 
         opts.on('-o', '--output=PATH',
           "Directory to output all this amazing documentation.",
-          "This option MUST be specified (unless --stdout).", " ") do |path|
-          @output_dir = canonical(path)
+          "This option MUST be specified (unless --stdout).",
+          "Use dash '-' to write docs to STDOUT (only export).", " ") do |path|
+          @output_dir = path == "-" ? :stdout : canonical(path)
         end
 
         opts.on('--ignore-global', "Turns off the creation of global class.", " ") do
@@ -152,16 +152,17 @@ module JsDuck
 
         opts.on('--meta-tags=PATH',
           "Path to Ruby file or directory with custom",
-          "meta-tag implementations. Experimantal!", " ") do |path|
-          @meta_tag_paths << path
+          "meta-tag implementations.", " ") do |path|
+          @meta_tag_paths << canonical(path)
         end
 
-        opts.on('--no-warnings', "Turns off warnings.", " ") do
-          @warnings = false
+        opts.on('--no-warnings',
+          "Turns off all warnings. Same as --warnings=-all", " ") do
+          Logger.instance.set_warning(:all, false)
         end
 
         opts.on('-v', '--verbose', "This will fill up your console.", " ") do
-          @verbose = true
+          Logger.instance.verbose = true
         end
 
         opts.separator "Customizing output:"
@@ -211,6 +212,11 @@ module JsDuck
           @examples = canonical(path)
         end
 
+        opts.on('--stats',
+          "Creates page with all kinds of statistics. Experimental!", " ") do
+          @stats = true
+        end
+
         opts.on('--categories=PATH',
           "Path to JSON file which defines categories for classes.", " ") do |path|
           @categories_path = canonical(path)
@@ -249,12 +255,11 @@ module JsDuck
           @img_tpl = tpl
         end
 
-        opts.on('--json', "Produces JSON export instead of HTML documentation.", " ") do
-          @export = :json
-        end
-
-        opts.on('--stdout', "Writes JSON export to STDOUT instead of writing to the filesystem", " ") do
-          @export = :stdout
+        opts.on('--export=TYPE',
+          "Exports docs in JSON.  TYPE is one of:",
+          "* full - full class docs.",
+          "* api  - only class- and member names.", " ") do |format|
+          @export = format.to_sym
         end
 
         opts.on('--seo', "Creates index.php that handles search engine traffic.", " ") do
@@ -270,6 +275,21 @@ module JsDuck
         opts.separator "Debugging:"
         opts.separator ""
 
+        opts.on('--warnings=+A,-B,+C', Array,
+          "Turns warnings selectively on/off.",
+          "+foo turns on a warning, -foo turns it off.",
+          "Possible warning types are:",
+          " ",
+          *Logger.instance.doc_warnings) do |warnings|
+          warnings.each do |op|
+            if op =~ /^([-+]?)(.*)$/
+              enable = !($1 == "-")
+              name = $2.to_sym
+              Logger.instance.set_warning(name, enable)
+            end
+          end
+        end
+
         # For debugging it's often useful to set --processes=0 to get deterministic results.
         opts.on('-p', '--processes=COUNT',
           "The number of parallel processes to use.",
@@ -369,7 +389,7 @@ module JsDuck
           @input_files << fname
         end
       else
-        $stderr.puts "Warning: File #{fname} not found"
+        Logger.instance.warn(nil, "File #{fname} not found")
       end
     end
 
@@ -387,7 +407,13 @@ module JsDuck
       if @input_files.length == 0 && !@welcome && !@guides && !@videos && !@examples
         puts "You should specify some input files, otherwise there's nothing I can do :("
         exit(1)
-      elsif @export != :stdout
+      elsif @output_dir == :stdout && !@export
+        puts "Output to STDOUT only works when using --export option."
+        exit(1)
+      elsif ![nil, :full, :api].include?(@export)
+        puts "Unknown export format: #{@export}"
+        exit(1)
+      elsif @output_dir != :stdout
         if !@output_dir
           puts "You should also specify an output directory, where I could write all this amazing documentation."
           exit(1)

data/lib/jsduck/renderer.rb

@@ -17,7 +17,7 @@ module JsDuck
             "<div class='doc-contents'>",
               render_private_class_notice,
               @cls[:doc],
-              render_meta_data,
+              render_meta_data(@cls[:meta]),
             "</div>",
             "<div class='members'>",
               render_member_sections,
@@ -35,9 +35,11 @@ module JsDuck
       ]
     end
 
-    def render_meta_data
+    def render_meta_data(meta_data)
+      return if meta_data.size == 0
+
       @meta_tags.map do |tag|
-        contents = @cls[:meta][tag.name]
+        contents = meta_data[tag.name]
         if contents
           tag.to_html(contents)
         else
@@ -136,9 +138,9 @@ module JsDuck
         statics = @cls[:statics][sec[:type]]
         if members.length > 0 || statics.length > 0
           [
-            "<div id='m-#{sec[:type]}'>",
+            "<div class='members-section'>",
               statics.length == 0 ? "<div class='definedBy'>Defined By</div>" : "",
-              "<h3 class='members-title'>#{sec[:title]}</h3>",
+              "<h3 class='members-title icon-#{sec[:type]}'>#{sec[:title]}</h3>",
               render_subsection(members, statics.length > 0 ? "Instance #{sec[:title]}" : nil),
               render_subsection(statics, "Static #{sec[:title]}"),
             "</div>",
@@ -165,11 +167,11 @@ module JsDuck
       first_child = is_first ? "first-child" : ""
       # shorthand to owner class
       owner = m[:owner]
-      # use classname "inherited" when member is not defined in this class
-      inherited = owner == @cls[:name] ? "not-inherited" : "inherited"
+      # is this method inherited from parent?
+      inherited = (owner != @cls[:name])
 
       return [
-        "<div id='#{m[:id]}' class='member #{first_child} #{inherited}'>",
+        "<div id='#{m[:id]}' class='member #{first_child} #{inherited ? 'inherited' : 'not-inherited'}'>",
           # leftmost column: expand button
           "<a href='#' class='side expandable'>",
             "<span>&nbsp;</span>",
@@ -177,8 +179,10 @@ module JsDuck
           # member name and type + link to owner class and source
           "<div class='title'>",
             "<div class='meta'>",
-              "<a href='#!/api/#{owner}' rel='#{owner}' class='definedIn docClass'>#{owner}</a><br/>",
-              "<a href='source/#{m[:files][0][:href]}' target='_blank' class='viewSource'>view source</a>",
+              inherited ? "<a href='#!/api/#{owner}' rel='#{owner}' class='defined-in docClass'>#{owner}</a>" :
+                          "<span class='defined-in' rel='#{owner}'>#{owner}</span>",
+              "<br/>",
+              "<a href='source/#{m[:files][0][:href]}' target='_blank' class='view-source'>view source</a>",
             "</div>",
             # method params signature or property type signature
             render_signature(m),
@@ -202,7 +206,7 @@ module JsDuck
       name = m[:name]
       before = ""
       if m[:tagname] == :method && m[:name] == "constructor"
-        before = "<strong class='constructor-signature'>new</strong>"
+        before = "<strong class='new-keyword'>new</strong>"
         name = @cls[:name]
       end
 
@@ -218,19 +222,19 @@ module JsDuck
 
       after = ""
       if m[:protected]
-        after += "<strong class='protected-signature'>protected</strong>"
+        after += "<strong class='protected signature'>protected</strong>"
       end
       if m[:static]
-        after += "<strong class='static-signature'>static</strong>"
+        after += "<strong class='static signature'>static</strong>"
       end
       if m[:deprecated]
-        after += "<strong class='deprecated-signature'>deprecated</strong>"
+        after += "<strong class='deprecated signature'>deprecated</strong>"
       end
       if m[:required]
-        after += "<strong class='required-signature'>required</strong>"
+        after += "<strong class='required signature'>required</strong>"
       end
       if m[:template]
-        after += "<strong class='template-signature'>template</strong>"
+        after += "<strong class='template signature'>template</strong>"
       end
 
       uri = "#!/api/#{m[:owner]}-#{m[:id]}"
@@ -258,7 +262,7 @@ module JsDuck
       if m[:deprecated]
         v = m[:deprecated][:version] ? "since " + m[:deprecated][:version] : ""
         doc << [
-          "<div class='deprecated'>",
+          "<div class='signature-box deprecated'>",
           "<p>This #{m[:tagname]} has been <strong>deprecated</strong> #{v}</p>",
           m[:deprecated][:text],
           "</div>",
@@ -267,13 +271,15 @@ module JsDuck
 
       if m[:template]
         doc << [
-          "<div class='template'>",
+          "<div class='signature-box template'>",
           "<p>This is a template method. A hook into the functionality of this class.",
           "Feel free to override it in child classes.</p>",
           "</div>",
         ]
       end
 
+      doc << render_meta_data(m[:meta])
+
       doc << render_params_and_return(m)
 
       doc

data/lib/jsduck/search_data.rb

@@ -29,8 +29,8 @@ module JsDuck
       return {
         :cls => cls.full_name,
         :member => cls.short_name,
-        :type => :cls,
-        :xtypes => cls[:xtypes]
+        :type => :class,
+        :aliases => cls[:aliases]
       }
     end
 

data/lib/jsduck/source_writer.rb

@@ -1,16 +1,29 @@
+require 'jsduck/logger'
+require 'fileutils'
+
 module JsDuck
 
   # Writes HTML JavaScript/CSS source into HTML file.
   class SourceWriter
 
+    # Writes all source files as HTML files into destination dir.
+    #
+    # Can't be done in parallel, because file.html_filename= method
+    # updates all the doc-objects related to the file
+    def self.write_all(files, destination)
+      FileUtils.mkdir(destination)
+      src = SourceWriter.new(destination)
+      files.each do |file|
+        html_filename = src.write(file.to_html, file.filename)
+        Logger.instance.log("Writing source", html_filename)
+        file.html_filename = File.basename(html_filename)
+      end
+    end
+
     # Initializes SourceFormatter to the directory where
     # HTML-formatted source files will be placed.
-    #
-    # Wrapper can be either :page or nil; with the first one the whole
-    # HTML page is created, otherwise source is left as is.
-    def initialize(output_dir, wrapper = :page)
+    def initialize(output_dir)
       @output_dir = output_dir
-      @wrapper = wrapper
     end
 
     # Writes HTML into file in output directory.  It returns the name
@@ -18,7 +31,7 @@ module JsDuck
     def write(source, filename)
       fname = uniq_html_filename(filename)
       File.open(fname, 'w') do |f|
-        f.write(@wrapper ? wrap_page(source) : source)
+        f.write(wrap_page(source))
       end
       fname
     end

data/lib/jsduck/stats.rb

@@ -0,0 +1,103 @@
+
+module JsDuck
+
+  # Calculates all kinds of statistics for classes
+  class Stats
+    # Maps array of classes into array of stats per class
+    def create(classes)
+      @classes = classes
+
+      classes.map do |cls|
+        local_members = cls.all_local_members
+        total_members = cls.all_members
+        class_wc = wc(cls[:doc])
+        members_wc = members_wc(cls)
+
+        {
+          :name => cls[:name],
+
+          :local_cfgs => member_count(local_members, :cfg),
+          :local_properties => member_count(local_members, :property),
+          :local_methods => member_count(local_members, :method),
+          :local_events => member_count(local_members, :event),
+          :local_members => local_members.length,
+
+          :total_cfgs => member_count(total_members, :cfg),
+          :total_properties => member_count(total_members, :property),
+          :total_methods => member_count(total_members, :method),
+          :total_events => member_count(total_members, :event),
+          :total_members => total_members.length,
+
+          :fanIn => fan_in(cls),
+          :fanOut => fan_out(cls),
+
+          :class_wc => class_wc,
+          :members_wc => members_wc,
+          :wc_per_member => local_members.length > 0 ? (members_wc / local_members.length) : 0,
+        }
+      end
+    end
+
+    def member_count(members, type)
+      members.find_all {|m| m[:tagname] == type }.length
+    end
+
+    # How many classes depend on this class
+    def fan_in(cls)
+      fan_in_table[cls[:name]] || 0
+    end
+
+    # On how many classes this class depends on
+    def fan_out(cls)
+      dependencies(cls).length
+    end
+
+    # list of class names the class depends on
+    def dependencies(cls)
+      [
+        cls[:extends],
+        cls[:mixins],
+        cls[:requires],
+        cls[:uses],
+      ].compact.flatten.sort.uniq
+    end
+
+    # Returns map of class names to its fan-in number.
+    def fan_in_table
+      return @fi_table if @fi_table
+
+      @fi_table = {}
+      @classes.each do |cls|
+        dependencies(cls).each do |d|
+          @fi_table[d] = (@fi_table[d] || 0) + 1
+        end
+      end
+      @fi_table
+    end
+
+    # Counts nr of words in documentation of all members of class
+    def members_wc(cls)
+      cnt = 0
+      cls.all_local_members.each do |m|
+        cnt += wc(m[:doc])
+        (m[:params] || []).each {|p| cnt += property_wc(p) }
+        (m[:properties] || []).each {|p| cnt += property_wc(p) }
+        cnt += wc(m[:return][:doc]) if m[:return]
+      end
+      cnt
+    end
+
+    def property_wc(property)
+      cnt = wc(property[:doc] || "")
+      (property[:properties] || []).each {|p| cnt += property_wc(p) }
+      cnt
+    end
+
+    # Strips HTML and counts words in text
+    def wc(str)
+      str.gsub(/<\/?[^>]*>/, "").scan(/\w+/).length
+    end
+
+  end
+
+end